SDK Guides

TypeScript / JavaScript

Install

npm install paegents

Initialize

import { PaegentsSDK } from 'paegents'

const sdk = new PaegentsSDK({
  apiUrl: process.env.PAEGENTS_API_URL!,
  agentId: process.env.PAEGENTS_AGENT_ID!,
  apiKey: process.env.PAEGENTS_API_KEY!,
})

Bilateral Agreement Flow

const agreement = await sdk.createUsageAgreement({
  sellerAgentId: 'seller-agent',
  serviceId: 'svc_abc123',
  quantity: 100,
  unit: 'api_calls',
  pricePerUnitCents: 10,
  paymentMethod: { rail: 'stablecoin', provider: 'x402' },
  settlementModel: 'bilateral_escrow',
  activationVersion: 'v2',
  buyerWalletAddress: '0xBuyerWallet...',
})

// After seller acceptance:
// 1. GET /usage-agreements/{agreement_id}/activation-package
// 2. sign the buyer activation intent locally
// 3. if pkg.infraFee is pending, sign the separate infra fee permit too
// 4. POST /usage-agreements/{agreement_id}/activate-escrow
// 5. poll GET /usage-agreements/{agreement_id} until active

Use the API activation package as the source of truth for buyer signing. For bilateral escrow, activation may require two buyer-side authorizations: the escrow activation intent and a separate infra fee permit. Keep wallet signing local and poll for activation instead of assuming the agreement is active immediately.

Settlement Helpers

const options = await sdk.getSettlementActionOptions(agreementId, {
  action: 'seller_claim',
})

if (options.recommendedMode === 'sponsored') {
  // sign with the escrow helper and submit through the sponsored action wrapper
} else {
  // fetch unsigned calldata and submit from the signer wallet
}

The SDK exposes mode-selection and settlement wrappers for close, seller claim, and buyer withdraw without requiring direct REST orchestration in your application.

Policies and Approvals (Owner JWT)

const ownerJwt = process.env.OWNER_JWT!

await sdk.updateAgentPolicies(
  {
    approvals: { threshold_cents: 2000 },
    rails: { allowed: ['card', 'stablecoin'] },
  },
  'agent-123',
  ownerJwt,
)

const { approvals } = await sdk.listApprovals({ status: 'pending' }, ownerJwt)
if (approvals.length > 0) {
  await sdk.approveApproval(approvals[0].id, 'agent-123', ownerJwt)
}

Webhook Verification

import { verifyWebhookSignature } from 'paegents'

verifyWebhookSignature(signatureHeader, rawBody, process.env.PAEGENTS_WEBHOOK_SECRET!)

Python

Install

pip install paegents

Initialize

import os
from paegents import PaegentsSDK

sdk = PaegentsSDK(
    api_url=os.environ['PAEGENTS_API_URL'],
    agent_id=os.environ['PAEGENTS_AGENT_ID'],
    api_key=os.environ['PAEGENTS_API_KEY'],
)

Bilateral Agreement Flow

from paegents import UsageAgreementRequest

agreement = sdk.create_usage_agreement(
    UsageAgreementRequest(
        seller_agent_id='seller-agent',
        service_id='svc_abc123',
        quantity=100,
        unit='api_calls',
        price_per_unit_cents=10,
        payment_method={'rail': 'stablecoin', 'provider': 'x402'},
        settlement_model='bilateral_escrow',
        activation_version='v2',
        buyer_wallet_address='0xBuyerWallet...',
    )
)

# After seller acceptance:
# 1. GET /usage-agreements/{agreement_id}/activation-package
# 2. sign the buyer activation intent locally
# 3. if package.infra_fee is pending, sign the separate infra fee permit too
# 4. POST /usage-agreements/{agreement_id}/activate-escrow
# 5. poll GET /usage-agreements/{agreement_id} until active

Use the API activation package as the source of truth for buyer signing. For bilateral escrow, activation may require two buyer-side authorizations: the escrow activation intent and a separate infra fee permit. Keep wallet signing local and poll for activation instead of assuming the agreement is active immediately.

Settlement Helpers

options = sdk.get_settlement_action_options(
    agreement.agreement_id,
    action='buyer_withdraw',
)

if options.recommended_mode == 'sponsored':
    # sign with the escrow helper and submit through the sponsored wrapper
else:
    # fetch unsigned calldata and submit from the signer wallet

Sponsored gas is optional. The SDK exposes a supported mode-selection surface and keeps the direct wallet path available when the signer wants to broadcast personally.

Webhook Verification

from paegents import verify_webhook_signature

verify_webhook_signature(signature_header, raw_body, os.environ['PAEGENTS_WEBHOOK_SECRET'])

Direct Stablecoin Purchases

For one-off stablecoin payments without bilateral escrow, use the direct stablecoin flow. The platform fee (2% + $0.003, minimum $0.10) is collected via an EIP-2612 USDC permit before the x402 payment executes.

TypeScript

import { buildDirectStablecoinAgreement } from 'paegents'

const pkg = await buildDirectStablecoinAgreement({
  buyerPrivateKey: process.env.AGENT_PRIVATE_KEY!,
  sellerWallet: '0xSellerWallet...',
  amountCents: 500,
  resourceId: 'svc_abc123',
  gasWalletAddress: '0xGasWallet...',
  chainId: 84532,
  usdcPermitNonce: 0n,
  permitDeadline: BigInt(Math.floor(Date.now() / 1000) + 600),
})

const agreement = await sdk.createUsageAgreement({
  sellerAgentId: 'seller_agent_xyz',
  serviceId: 'svc_abc123',
  quantity: 1,
  unit: 'purchase',
  pricePerUnitCents: 500,
  settlementModel: 'direct_payment',
  buyerWalletAddress: pkg.buyerWalletAddress,
  paymentHeader: pkg.paymentHeader,
})

Python

from paegents import build_direct_stablecoin_agreement, UsageAgreementRequest

pkg = build_direct_stablecoin_agreement(
    buyer_private_key=os.environ['AGENT_PRIVATE_KEY'],
    seller_wallet='0xSellerWallet...',
    amount_cents=500,
    resource_id='svc_abc123',
    gas_wallet_address='0xGasWallet...',
    chain_id=84532,
    usdc_permit_nonce=0,
    permit_deadline=int(time.time()) + 600,
)

agreement = sdk.create_usage_agreement(
    UsageAgreementRequest(
        seller_agent_id='seller_agent_xyz',
        service_id='svc_abc123',
        quantity=1,
        unit='purchase',
        price_per_unit_cents=500,
        settlement_model='direct_payment',
        buyer_wallet_address=pkg['buyer_wallet_address'],
        payment_header=pkg['payment_header'],
    )
)

The builder handles x402 payment signing and fee permit signing in one call. On seller acceptance, the platform collects the fee first, then executes the x402 payment. If fee collection fails, the payment is rejected.