Dutiful

All guides

Paying an x402 API from an agent

An x402 client requests a resource, reads the payment terms returned with HTTP 402, and sends a signed payment payload. In a common x402 v2 flow, the server verifies and settles payment before returning the resource. Verification alone does not guarantee delivery.

The steps below explain the HTTP headers and payment setup, then show Dutiful's Company Report order flow. Sellers may have their own access requirements. For background, see What is x402?

The flow, step by step

The specification README describes a typical exchange between a client, a resource server and an optional facilitator, while noting that servers have flexibility and that the first two steps are unnecessary when the client already knows the payment details. In the typical flow:

  1. The client makes an ordinary HTTP request to a resource server.
  2. The server answers 402 Payment Required with a base64-encoded PaymentRequired object in a PAYMENT-REQUIRED header, listing what it accepts.
  3. The client selects one of the offered payment requirements and builds a payment payload matching that requirement's scheme and network.
  4. The client retries the request with the payload in a PAYMENT-SIGNATURE header.
  5. The server verifies the payload, either locally or by POSTing it to a facilitator's /verify endpoint.
  6. If verification passes, the server performs the work, settles the payment (directly onchain or through the facilitator's /settle endpoint) and returns 200 with the resource, plus a PAYMENT-RESPONSE header carrying the settlement response when payment was executed. Failed verification returns 402 again. Verification alone does not guarantee settlement or delivery; settlement and service failures need separate handling.

The pieces that decide whether payment works

Scheme and network. A scheme is a logical way of moving money. The spec README names exact (a fixed amount per request), upto (authorize a maximum, settle actual usage) and batch-settlement (EVM: escrow and off-chain vouchers redeemed onchain in batches). A scheme is implemented per network, so clients and facilitators must explicitly support the same (scheme, network) pair; exact on Ethereum works differently from exact on Solana.

Facilitator. A server that verifies and executes payments for one or more networks. The design goals state that a scheme must not let the facilitator or the resource server move funds other than as the client intended, and that gas and RPC details should be abstracted away from client and server. For production mainnet routes the README advises choosing a facilitator model explicitly - a production provider for your network, your own facilitator, or self-facilitation inside the resource server - rather than assuming the public x402.org facilitator is the default production path.

Client libraries. Reference SDKs exist for TypeScript (the @x402 package family, including a minimal fetch client), Python (pip install x402) and Go. SDK support varies by language, scheme and network. A suitable client integration can handle the payment challenge and signing flow, but still needs a funded wallet or signer, spending authority and service-specific request handling.

A worked example: Dutiful's Company Report API

Dutiful sells Company Reports over x402 and documents its flow publicly in its developer documentation. The order flow itself is specific to this API; the payment mechanics are standard x402 v2.

  1. Send POST /api/order to Dutiful with a company and country. This is a free coverage check: it returns candidate entities and needs no account or API key.
  2. POST the selected candidate index as {"idx": ...} to the order's entity endpoint. The response is 402 with standard x402 v2 payment requirements in a PAYMENT-REQUIRED header (3000000 USDC units, $3.00) and a pay_url in the body.
  3. Sign an EIP-3009 TransferWithAuthorization for exactly the requested amount of USDC on Base, then POST to the pay_url with the payload base64-encoded in a PAYMENT-SIGNATURE header.
  4. GET the order endpoint for status and, once delivered, the report.

Dutiful's developer documentation states the implementation details: the signature's validBefore must sit inside the maxTimeoutSeconds window given in the requirements (30 minutes); sign a fresh payload per order; send uint256 values as decimal strings, not JSON numbers; the buyer pays no gas because the facilitator broadcasts and settles. MCP exposes check_coverage (free), create_order (returns payment requirements; does not pay) and get_report. Payment still requires the separate HTTP payment flow or an MCP client with x402 wallet support.

Before connecting a client, check that it has compatible payment-challenge handling, a funded signer with an approved spending scope, and the service's order and retrieval logic. HTTP access alone is not enough. Wallet or library support must match the offered scheme, network and asset; service-specific access requirements can also apply.

Sources

x402 specification repository

Reference implementation README

Dutiful developer documentation

What is x402?

Run the free coverage check · See a sample report