Skip to main content

Covenant x402

x402 is HTTP 402 Payment Required turned into a working payment rail. A resource answers an unpaid request with a signed price quote, the caller pays on-chain, and the same request retried with an X-PAYMENT header returns the resource. Covenant uses x402 in both directions: agents pay for external resources, and Covenant exposes paid resources to other agents.

Both directions run through one accounting path. Settlement, budgeting, audit, and attestation are shared, so a paid call is a first-class, capability-gated, audited action rather than a side channel.

Crates

CrateRole
covenant-x402Core types (PaymentRequirements, PaymentExtra), the Signer trait, and PayaiSolanaSigner for Solana settlement.
covenant-x402-signerA stdin/stdout sidecar binary: read a PaymentRequirements JSON on stdin, get the base64 X-PAYMENT header value on stdout. Keeps signing out of process.

Money path (Solana)

  • Network and asset: Solana mainnet, USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v).
  • Facilitator: PayAI is the fee payer and the settler. It co-signs the transaction as feePayer (so it sponsors gas) and submits it.
  • Roles: the funder (the paying agent) partial-signs the transfer; the facilitator co-signs as fee payer and settles; the recipient (payTo) receives the USDC. Funder and recipient are always distinct accounts.
  • Fail closed: if the facilitator cannot settle, the caller receives a 402 and is never charged, and the resource is never released.

Paying for resources (outbound)

An agent reaches a paid provider through capability-gated MCP tools. The daemon signs the x402 payment with the agent funding key, debits the agent budget, writes a settlement receipt, and records the call in the hash-chained audit log. The agent never holds raw payment plumbing; it calls a tool and gets a result.

The covenant-x402-signer sidecar is the reusable primitive: feed it the PaymentRequirements from any 402 challenge and it returns the header to retry with.

export COVENANT_X402_FUNDING_KEYPAIR=/path/to/funder.json
export COVENANT_X402_RPC_URL=https://api.mainnet-beta.solana.com
echo "$payment_requirements_json" | covenant-x402-signer   # -> base64 X-PAYMENT header

Exposing a paid resource (inbound)

Covenant runs a public x402 seller at https://x402-seller.opencovenant.org. It sells Covenant-signed trust reads, all advertised at GET /.well-known/x402:

GET  /x402/passport/<mpl-core-asset>   verify an on-chain identity passport
POST /x402/attest                      a Covenant-signed attestation over a claim
GET  /x402/payai/reputation/<wallet>   a wallet's PayAI settlement-grounded reputation
GET  /x402/er/enclave/<validator>      a live TDX verification of a MagicBlock ephemeral rollup

Unpaid, each returns an x402 v2 402 challenge: the exact scheme, Solana mainnet, USDC, payTo the Covenant treasury, feePayer the PayAI sponsor, priced per call (currently $0.001 to $0.01). Pay and retry to receive the signed result. Returning a status of 400 or higher from the resource cancels settlement, so a caller is never charged for an error.

The endpoints are discoverable and monitored:

  • GET /.well-known/x402 advertises them so crawlers (the zauth directory, x402scan) can list the resources.
  • They are registered and health-monitored in the zauth provider hub on Solana mainnet.

Related