x402 Payments#

Hightop exposes a launch-ready x402 signing route outside the Agent API v1 namespace:

textexample

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

This route is agent-callable, but it is not a /v1/agent/* endpoint and does not create an AgentOperation.

Auth#

The source route uses authType: 'agent'. Use agent credentials:

textexample

x-agent-id: <agent uuid>
x-api-key: <agent api key>

The owner account must be approved. New or unapproved test accounts may authenticate successfully and still be rejected by this legacy action route.

Do not assume OAuth support for this legacy route unless Hightop confirms it for your integration.

Request#

jsonexample

{
  "payTo": "0x0000000000000000000000000000000000000000",
  "amount": "1000000",
  "targetUrl": "https://example.com/paid-api",
  "maxTimeoutSeconds": 300,
  "idempotencyKey": "x402-payment-001"
}

Fields:

Field	Type	Required
`payTo`	Ethereum address	Yes
`amount`	USDC base units as a string-compatible integer	Yes
`targetUrl`	URL	No
`maxTimeoutSeconds`	positive integer, max 600	No
`idempotencyKey`	nonempty string, max 128 chars	No

amount is USDC base units with 6 decimals. "1000000" means 1 USDC.

Response#

jsonexample

{
  "paymentHeader": "base64-encoded-x402-payment",
  "nonce": "0x...",
  "amount": "1000000",
  "payTo": "0x0000000000000000000000000000000000000000",
  "validBefore": "1760000000"
}

Flow#

textexample

agent requests paid service
  -> service returns HTTP 402 payment requirements
  -> agent asks Hightop to sign an x402 payment
  -> Hightop may top up the per-wallet CDP signer EOA from the Hightop wallet
  -> Hightop returns a payment header
  -> agent retries the service request with the payment header
  -> settlement task marks the payment settled or expired

The signed payload uses x402 version 1, scheme exact, network base, and a USDC EIP-3009 transfer authorization.

Idempotency#

Pass idempotencyKey to safely retry without double-signing. Hightop returns the original payment header when it finds an existing payment for the same user and idempotency key.

This idempotency field is in the JSON body, not the Agent API Idempotency-Key header.

Lifecycle#

x402 payments are persisted as pending records and later become settled or expired through the settlement check task. They create Hightop Activity. They are not AgentOperation rows unless Hightop changes the source route.

Errors#

This route uses the legacy action error surface, not the Agent API v1 error-code contract. Common failures include invalid request shape, insufficient USDC available to top up the signer EOA, signing failure, and auth failure.