x402 Payments#

The Agent API v1 exposes first-class x402 routes under /v1/agent/x402/*. They use snake_case fields, the standard Agent API Idempotency-Key header, and operation-backed responses (operation_id). Prefer these for new integrations. A separate legacy action route predates v1 and is documented at the end.

Routes#

Quote#

Fetch a URL and report its x402 price without paying. Read-only, so no idempotency key.

curl -sS https://api.hightop.com/v1/agent/x402/quote \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "url": "https://example.com/paid-api", "method": "GET" }'

Request: url (required), method, body, timeout_ms. Response includes supported, x402_required, and a price object.

Supported challenges use the exact scheme on Base USDC. Sellers may return the challenge in the 402 JSON body or in a response header. x402 v1 challenges commonly use network: "base" in the body. x402 v2 challenges may use CAIP-2 network IDs such as eip155:8453 and may be header-only — supplied in the inbound PAYMENT-REQUIRED response header rather than the body. (That inbound seller-challenge header is separate from the outbound retry headers, where clients follow payment_header_name / payment_headers.) quote and purchase follow the challenge fields returned by the seller instead of hardcoding a protocol version, network string, or retry header name.

Purchase#

The one-call path: fetch the URL, satisfy the x402 challenge, and return the upstream response. Requires an idempotency key and returns an operation.

curl -sS https://api.hightop.com/v1/agent/x402/purchase \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: x402-$(uuidgen)" \
  -d '{ "url": "https://example.com/paid-api", "max_amount": "1000000", "method": "GET" }'

Request: url (required), max_amount (required), method, body. max_amount is a USDC base-unit integer string (6 decimals): "1000000" means a 1 USDC cap. Response includes operation_id, paid, seller_accepted, settled, and the upstream response.

Sign#

The lower-level path: sign an x402 payment authorization yourself, then retry the seller request with the returned header. Requires an idempotency key and returns an operation.

curl -sS https://api.hightop.com/v1/agent/x402/sign \
  -H "x-agent-id: $HIGHTOP_AGENT_ID" -H "x-api-key: $HIGHTOP_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: x402-$(uuidgen)" \
  -d '{ "target_url": "https://example.com/paid-api", "pay_to": "0x...", "amount": "1000000" }'

Request: target_url, pay_to, amount, max_timeout_seconds, or a full payment_requirements object. amount is a USDC base-unit integer string (6 decimals): "1000000" means 1 USDC. Response includes operation_id, payment_version, payment_header (and payment_header_name / payment_headers), nonce, and valid_before. Add the returned header(s) to your retried request.

Flow#

agent requests a paid service
  -> service returns HTTP 402 with payment requirements
  -> agent calls /v1/agent/x402/quote (optional) to inspect the price
  -> agent calls /v1/agent/x402/purchase (one-shot) OR /v1/agent/x402/sign (manual)
  -> Hightop signs an x402 (EIP-3009 USDC transfer authorization on Base)
  -> agent retries the service request with the payment header(s)
  -> the operation settles and creates Hightop Activity

The signed payload and retry header follow the seller's challenge. Use the returned payment_header_name / payment_headers fields rather than assuming a fixed x402 version, network value, or header name.

Idempotency and errors#

sign and purchase follow the standard Agent API contract: pass the Idempotency-Key header, poll the returned operation_id to a terminal status, and branch on the stable error codes. quote creates no state and needs no key. See Conventions and Going to Production.

See the Pay with x402 recipe for an end-to-end walkthrough.

Legacy action route#

A pre-v1 signing route also exists outside the /v1/agent/* namespace:

POST https://api.hightop.com/api/actions/x402/sign

It differs from the v1 routes: camelCase fields (payTo, targetUrl, maxTimeoutSeconds), a body-level idempotencyKey (not the Idempotency-Key header), no AgentOperation (it persists a pending payment record that later becomes settled/expired), and the legacy action error surface rather than the v1 error-code contract. It is agent-callable with header-key auth; do not assume OAuth support. Prefer the v1 routes above unless you are maintaining an existing legacy integration.