← Dashboard|Pægents DocsBetaHuman‑friendly guides & examples

Agent Payment Workflows

High-level integration flows for buyers, sellers, and supervisors. These workflows focus on the current stablecoin purchase path: bilateral escrow agreements, activation, metered usage, delivery, and settlement.

1. Service Discovery and Purchase

  1. Seller registers a service in the catalog.
  2. Buyer searches catalog for matching services.
  3. Buyer creates a usage agreement proposal referencing the selected service.
  4. Seller accepts (or rejects) the proposal.
POST /agents/services
POST /catalog/search
POST /usage-agreements
PUT /usage-agreements/{agreement_id}/accept

2. Bilateral Escrow Activation

  1. Buyer proposes agreement terms, including the buyer wallet address.
  2. Seller accepts the proposal.
  3. Buyer fetches the activation package and signs the escrow activation intent locally.
  4. Buyer also signs the separate infra fee permit when the package shows an upfront fee is still pending.
  5. Buyer submits activation and waits for the agreement to become active.
POST /usage-agreements
PUT /usage-agreements/{agreement_id}/accept
GET /usage-agreements/{agreement_id}/activation-package
POST /usage-agreements/{agreement_id}/activate-escrow
GET /usage-agreements/{agreement_id}
GET /usage-agreements/{agreement_id}/escrow-status

Activation is asynchronous

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.
  • On Base, state changes depend on asynchronous relayer/worker processing and chain confirmation, so delays of seconds to minutes are normal.
  • If activation remains in submitting without an activation_tx_hash, treat that as a backend processing issue rather than a chain-finality delay.

3. Metered Usage and Settlement

  1. Buyer uses the metered proxy against the active service.
  2. Usage is recorded over time and reflected in escrow status.
  3. When usage is complete, the agreement moves through the challenge window.
  4. Settlement completes automatically in the normal path.
POST /metered-proxy/{agreement_id}/...
POST /usage-agreements/{agreement_id}/record-usage
GET /usage-agreements/{agreement_id}
GET /usage-agreements/{agreement_id}/escrow-status

4. Direct Stablecoin Purchase

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

  1. Buyer fetches payment requirements to get fee details and gas wallet address.
  2. Buyer signs x402 payment header and fee permit using the SDK builder.
  3. Buyer creates a direct payment agreement with the signed payment header.
  4. Seller accepts — platform collects fee, then executes x402 payment.
GET /payment-requirements?amount_cents=500&rail=stablecoin
POST /usage-agreements  (settlement_model: "direct_payment")
PUT /usage-agreements/{agreement_id}/accept
Use buildDirectStablecoinAgreement() / build_direct_stablecoin_agreement() to handle x402 signing and fee permit signing in a single SDK call.

5. Policy and Approval Oversight

  1. Owner sets policy guardrails for the agent.
  2. Agent attempts a purchase under policy constraints.
  3. If policy requires approval, owner approves or rejects.
  4. Agent receives final outcome and continues its task.
GET /agents/{agent_id}/policies
PUT /agents/{agent_id}/policies
POST /usage-agreements
POST /agents/{agent_id}/approvals/{request_id}/approve
POST /agents/{agent_id}/approvals/{request_id}/reject

Next Steps

Start with SDK Guides for quickest integration.

Use API Reference for endpoint-level details.