x402 & Machine 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.

Agents can already call APIs. The harder part is paying for them without human checkout, long-lived billing setup, or broad custody. Machine-payment protocols put payment into the same request flow as access.

Hightop's role is the account and control layer behind those flows. The agent still pays from the same Hightop account, inside the same lane, under the same permissions and limits.

Where Hightop Is Today#

x402 is a first-class part of the Agent API v1, via:

text

example

POST /v1/agent/x402/quote
POST /v1/agent/x402/sign
POST /v1/agent/x402/purchase

These use snake_case fields, the Agent API Idempotency-Key header, and operation-backed responses. A pre-v1 POST /api/actions/x402/sign action route also still exists (camelCase, body-level idempotencyKey, no AgentOperation) but is legacy. Prefer the v1 routes.

MPP is not yet in the Agent API. Treat it as an emerging protocol direction, not a callable Hightop API surface today.

What x402 Is#

x402 is a payment protocol built around HTTP 402 Payment Required. A service can return payment requirements, the client can obtain a payment authorization, and the original request can be retried with payment attached.

In Hightop, the current x402 route signs a USDC payment authorization on Base from a per-wallet signer EOA. Hightop may top up that signer from the Hightop wallet, returns a payment header, and records settlement as Activity.

What MPP Is#

MPP, short for Machine Payments Protocol, is an emerging machine-payments protocol from Stripe and Tempo. It is aimed at machine-to-machine payment flows that may include API access, agent-to-agent commerce, micropayments, or recurring usage.

MPP is not a current Agent API endpoint. Hightop can support additional machine-payment surfaces as they become real and useful, but builders should not design against an MPP Hightop route until one is published.

Why Machine Payments Matter#

Most web commerce assumes a human:

creates an account
enters a card
chooses a plan
manages billing
handles failed payment recovery

Agents need lower-friction payment flows. A research agent buying one data query or an operations agent paying for one tool call should not need a new billing relationship every time.

How Machine Payments Fit Hightop#

Machine-payment protocols sit at the edge of Hightop. They do not replace the Hightop account, wallet, rules, monitoring, or revocation model.

text

example

agent
  -> machine-payment protocol
  -> Hightop account and controls
  -> stablecoin settlement

The protocol can change. The Hightop lane still controls what the agent is allowed to spend, where, and under what limits.

x402 Routes#

Endpoint paths are relative to /v1/agent

Method	Path	Scope	Idempotency
POST	/x402/quote	`agent:simulate`	not required
POST	/x402/sign	`agent:payments:write`	required
POST	/x402/purchase	`agent:payments:write`	required

Quote#

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

curl

request

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

request

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

request

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#

text

example

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.

Where to Go Next#

Legacy action route#

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

text

example

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.