# CoinVoyage x402 Payment-Required Example

x402 resource:
- Name: x402 Payment-Required
- Description: One-cent x402 gated resource for testing PayKit headless payments.
- Human page: undefined/agent/x402
- HTTP endpoint: GET undefined/api/agent/payment-required
- OpenAPI contract: undefined/api/agent/payment-required/openapi.json
- Tool contract: undefined/api/agent/payment-required/tools
- Price: $0.01 USD
- Payment protocol: x402 v2
- Payment headers: PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE
- Accepted rails: exact token payments on EVM, Solana, and Sui when present in accepts[]
- Accepted assets: supported token assets offered in accepts[] on EVM, Solana, or Sui
- Not currently supported: native ETH and native SOL accepts
- Human UI test options: USDC on Base, Solana, and Sui

Sui support requirements:
- Sui accepts are payable by @coin-voyage/paykit-headless clients that implement CoinVoyage's Sui PAYMENT-SIGNATURE payload. Generic EVM or Solana x402 clients cannot pay a sui:mainnet accept.
- To pay Sui from an agent, install @coin-voyage/paykit-headless and use executeX402AgentPayment or createSuiX402PaymentSignatureHeader from @coin-voyage/paykit-headless/x402.
- Do not infer a Sui payload from amount and payTo alone. Do not send a Sui transaction digest, an EIP-3009 payload, a Solana SVM payload, or JSON that only repeats the amount.
- To pay Sui, choose a returned accepts[] entry with network sui:mainnet and keep scheme, network, asset or assetAddress, amount, payTo, and paymentIdentifier unchanged.
- The SDK-generated PAYMENT-SIGNATURE is base64 JSON containing the selected accept plus signed Sui transaction bytes, signature, and payer address in CoinVoyage's Sui payload shape. The verifier reads the signed transaction and rejects it if amount, coin type, recipient, payer, or paymentIdentifier differs from the requirement.
- If your client cannot install or use @coin-voyage/paykit-headless, request or select Base or Solana instead.

Flow:
1. Create or choose the Order to complete.
2. Request the initial PAYMENT-REQUIRED challenge from the Order /x402/complete endpoint. No JSON body is required.
3. To state a preferred token asset or chain, include X402RequirementRequest fields with both preferred_chain_type and preferred_token_address. If no preference is stated, omit all preference fields and choose any supported token accepts[] entry on a CoinVoyage-supported chain.
4. If the response is 402, decode the PAYMENT-REQUIRED base64 JSON header.
5. Choose a returned accepts[] entry and keep its network, scheme, asset or assetAddress, amount, payTo, and paymentIdentifier unchanged. Do not choose native ETH or native SOL accepts. Choose Sui only when your client implements the Sui support requirements above.
6. Pay according to that entry's network.
7. Retry GET undefined/api/agent/payment-required with PAYMENT-SIGNATURE containing the selected payment payload.

X402RequirementRequest preference fields:
- The whole preference request is optional. If you send it, preferred_chain_type and preferred_token_address are required together.
- Do not send only preferred_chain_type, such as preferred_chain_type=SUI. Either include the token address or omit all preference fields.
- preferred_chain_type: EVM, SOL, or SUI.
- preferred_chain_id: optional chain id for the requested rail. Base is 8453, Solana is 30000000000001, Sui is 30000000000002.
- preferred_token_address: required token contract address, Solana mint, or Sui coin type when preferred_chain_type is provided.

Example tailored Base USDC challenge request using preference fields:
POST undefined/orders/{orderId}/x402/complete
Content-Type: application/json

{"preferred_chain_id":8453,"preferred_chain_type":"EVM","preferred_token_address":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"}

The local demo endpoint also accepts payment preferences as query parameters and forwards them to /x402/complete:
GET undefined/api/agent/payment-required?orderId={orderId}&preferred_chain_type=EVM&preferred_chain_id=8453&preferred_token_address=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913

Example tailored Sui USDC challenge request:
GET undefined/api/agent/payment-required?orderId={orderId}&preferred_chain_type=SUI&preferred_chain_id=30000000000002&preferred_token_address=0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC