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 a Covenant agent reputation and attestation lookup:

GET /x402/agent/<solana-pubkey>

Unpaid, it returns an x402 v2 402 challenge: the exact scheme, Solana mainnet, USDC, payTo the Covenant treasury, feePayer the PayAI sponsor, price $0.001. Pay and retry, and it returns a covenant_agent_attestation_v0 object for that pubkey. Returning a status of 400 or higher from the resource cancels settlement, so a caller is never charged for an error.

The endpoint is discoverable and monitored:

  • GET /.well-known/x402 advertises the resource so crawlers (the zauth directory, x402scan) can list it.
  • It is registered and health-monitored in the zauth provider hub on Solana mainnet.

The v0 attestation surface returns verified on-chain presence today; richer reputation fields wire to the Covenant audit and reputation layer next.

Related