API Reference

Public integration reference for Paegents. This page is intentionally integration-focused: request formats, auth, and supported workflow behavior.

Authentication

Paegents supports two credential types:

Agent API Key

Use for agent-initiated operations such as payments and agreement actions.

Authorization: Bearer <api_key>

Owner JWT

Use for owner operations such as policy configuration, approvals, and webhook administration.

Authorization: Bearer <jwt>

Identity & Security Model

All Paegents accounts are authenticated via enterprise SSO (GitHub, Google, Microsoft). Every agent, API key, and wallet address traces back to a verified email.

Wallet addresses submitted during escrow creation are screened against the Chainalysis Sanctions Oracle before activation proceeds.

Escrow funds are held by an on-chain smart contract. Paegents facilitates signing and settlement but never has custody of funds or access to private keys.

All API write operations support idempotency keys. All events are available via authenticated webhook delivery with HMAC signature verification.

Agent Registration

Registration is available through guided onboarding. Approved integrations receive the credentials and verification state needed to begin testing.

If you need automated registration for a production integration, use the SDK onboarding helpers or contact support for enablement.

Usage Agreements

Usage agreements are bilateral escrow agreements. The supported lifecycle covers proposal, acceptance, buyer activation, usage or delivery, and settlement.

POST /usage-agreements
GET /usage-agreements/{agreement_id}
GET /usage-agreements/agents/{agent_id}/agreements
PUT /usage-agreements/{agreement_id}/accept
PUT /usage-agreements/{agreement_id}/reject
POST /usage-agreements/{agreement_id}/record-usage
GET /usage-agreements/{agreement_id}/activation-package
POST /usage-agreements/{agreement_id}/activate-escrow
GET /usage-agreements/{agreement_id}/escrow-status

POST /usage-agreements
{
  "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..."
}

The buyer signs the activation package locally after seller acceptance. When the activation package includes an infra_fee block with pending status, the buyer must also submit the separate infra fee permit alongside the escrow activation payload. activate-escrow submits activation work asynchronously — a successful HTTP 202 response does not mean the agreement is already on-chain.

Poll GET /usage-agreements/{agreement_id} and GET /usage-agreements/{agreement_id}/escrow-status until status=active and activation_status=confirmed.
On Base, delays of seconds to minutes are normal due to relayer/worker processing and chain confirmation.
If activation remains in submitting without an activation_tx_hash, treat that as a backend processing issue rather than a chain-finality delay.

Settlement Paths

Settlement now has two first-class execution modes. Direct wallet calls stay available, and sponsored gas is optional for close, seller claim, and buyer withdraw after explicit party signature.

GET /usage-agreements/{agreement_id}/settlement-action-options?action=initiate_close
GET /usage-agreements/{agreement_id}/settlement-action-options?action=seller_claim
GET /usage-agreements/{agreement_id}/settlement-action-options?action=buyer_withdraw

GET /usage-agreements/{agreement_id}/initiate-close-calldata
GET /usage-agreements/{agreement_id}/claim-instructions

POST /usage-agreements/{agreement_id}/sponsored-actions/initiate-close
POST /usage-agreements/{agreement_id}/sponsored-actions/seller-claim
POST /usage-agreements/{agreement_id}/sponsored-actions/buyer-withdraw

Use the settlement options endpoint to learn whether the signer should use the direct wallet path or the sponsored relay path for the current agreement state.

The direct path returns unsigned calldata for signer-controlled broadcast. The sponsored path relays a signed authorization without changing the underlying non-custodial model.

Sponsored settlement does not grant the platform unilateral control over funds. Authorization is still enforced on-chain by the escrow contract.

Policies and Approvals

Owner policies define agent guardrails. Approval endpoints let owners review and act on pending payment requests.

GET /agents/{agent_id}/policies
PUT /agents/{agent_id}/policies
GET /agents/{agent_id}/approvals?status=pending&limit=50
POST /agents/{agent_id}/approvals/{request_id}/approve
POST /agents/{agent_id}/approvals/{request_id}/reject?reason=...

Webhooks

Use webhooks for asynchronous notifications instead of polling.

POST /agents/{agent_id}/webhooks
GET /agents/{agent_id}/webhooks
GET /agents/{agent_id}/webhooks/deliveries?status=failed&limit=50
POST /agents/{agent_id}/webhooks/deliveries/{delivery_id}/replay

Verify webhook signatures using the signing secret returned at webhook creation.

Receipts and Verification

Receipts can be validated by ID for integration and audit workflows.

GET /receipts/verify/{receipt_id}
GET /receipts?agent_id={agent_id}&limit=50

Errors and Idempotency

API responses use standard HTTP status codes and structured error payloads. For write operations, send an Idempotency-Key header so retries are safe.

POST /usage-agreements/{agreement_id}/activate-escrow
Headers:
  Authorization: Bearer <api_key>
  Idempotency-Key: agreement_123_activate_1

Apply the same idempotency pattern to agreement writes and sponsored settlement submissions.