x402 Developer Quick Start

x402 is GOAT Network's HTTP-native payment protocol for APIs, apps, and agents. It turns the standard HTTP 402 Payment Required response into a practical payment flow: your backend creates an order, returns a machine-readable payment payload to the client, verifies the payment after the user signs or submits it, and then completes the protected action.

Use this quick start when you want to add x402 payments to a real application. It walks through the main decisions and integration steps in order: preparing your local backend environment, choosing between DIRECT and DELEGATE payment modes, completing merchant onboarding, configuring backend credentials, creating the first order, handling the user payment, and verifying the final order status and proof. If your application needs payment-triggered contract execution, the DELEGATE section also covers callback contract setup, review, caller authorization, and production validation.

Before You Start

Prepare a development environment where you can run a backend service and validate wallet-based payments against the target environment you plan to use.

You will need:

• Node.js and pnpm installed locally
• a backend project or API route where server-side code can run
• an EVM wallet for testing payment flows
• RPC access for the chain you plan to test on
• a place to store local environment variables, such as .env

If you are integrating through AgentKit, use AgentKit x402 Payments instead of starting from the raw repo.

Step 1: Choose the Target Environment

x402 supports separate production and test environments. Use the credentials, supported tokens, payment chains, and API base URL issued for the environment you are integrating with.

For production:

For GOAT Network testnet3:

Order request fields are the same across test and production environments. Use the same API schema, and change only the API base URL, credentials, merchant ID, supported token configuration, and chain or token values for the selected environment.

Step 2: Choose the Payment Mode

Start by matching x402's payment mode to what should happen after the user pays.

Use DIRECT when the payment itself is the final action, such as unlocking an API response, content, download, or other off-chain delivery.

Use DELEGATE when payment settlement needs to trigger additional execution after the user pays, such as calling a smart contract through a callback flow.

This choice affects merchant setup, order creation, callback metadata, status handling, and production validation.

See Payment Modes for the full decision guide.

Step 3: Complete Merchant Onboarding

Apply for an x402 merchant account before configuring your backend. Use the x402 Merchant Portal to submit the merchant application or sign in if your account has already been approved.

After you submit the application, wait for the platform review to complete. The merchant ID, API credentials, supported payment configuration, and receive type are issued after approval for the selected environment.

After approval, collect:

• merchant ID
• API key
• API secret
• supported tokens and chains
• receive type: DIRECT or DELEGATE

For testing and production, make sure the merchant receive type matches the payment mode used by your application. A DIRECT merchant should be used for direct settlement flows. A DELEGATE merchant should be used when settlement needs to trigger callback execution.

For DELEGATE integrations, confirm the callback metadata requirements with the x402 operator or merchant portal before deploying your adapter contract. This includes the destination chain_id and callback contract review process.

eip712_name and eip712_version are optional EIP-712 domain strings. If your callback flow uses them, enter the exact values expected by your signing flow and keep casing, spaces, and punctuation identical across the backend, signing payload, callback contract, and operator records.

Step 4: Configure Backend Credentials

Store x402 credentials on your backend.

GOATX402_API_URL=https://x402-api.goat.network
GOATX402_API_KEY=your_api_key
GOATX402_API_SECRET=your_api_secret
GOATX402_MERCHANT_ID=your_merchant_id

GOATX402_API_URL=https://x402-api-lx58aabp0r.testnet3.goat.network/
GOATX402_API_KEY=your_api_key
GOATX402_API_SECRET=your_api_secret
GOATX402_MERCHANT_ID=your_merchant_id

Use the API URL and credentials for the selected environment. Keep test and production credentials separate.

Step 5: Load Merchant Configuration

Before creating orders, fetch the selected merchant configuration from GET /merchants/{merchant_id}. Use the returned wallets entries to build the supported payment routes for your app.

Each wallet entry identifies a supported chain and token:

• chain_id
• token_symbol
• token_contract

If the response does not include token decimals, resolve decimals from local token metadata or by reading the token contract. Frontends should only display payment routes that are both returned by the merchant API and supported by the wallet or chain metadata in the app.

Step 6: Create the First Order

Your backend should call the order creation endpoint and be prepared for payment-required protocol responses. Depending on the SDK or integration layer, an x402 payment requirement may surface as an HTTP 402 response or as a normalized successful response containing the payment payload.

Frontend -> backend create-order route
Backend -> x402 create order
x402 -> backend returns payment payload
Frontend -> signs / pays
Backend -> polls status and retrieves proof

For DIRECT flows, the order can represent a simple payment-gated action.

For DELEGATE flows, include the callback calldata required by your callback contract when creating the order. The callback contract itself is configured through the merchant callback metadata, not passed as part of each order. See Payment Modes for the full DELEGATE callback setup.

When your frontend uses internal names such as settlementChainId, settlementTokenSymbol, or settlementTokenContract, map them to the x402 create-order fields chain_id, token_symbol, and token_contract on the backend.

Step 7: Handle User Payment

After the backend returns the x402 payment payload, the client should present the payment request to the user and guide them through signing or paying with the supported payment flow.

The frontend should not receive merchant API secrets. It should only receive the payment payload, public order state, and any user-facing payment metadata required to complete the transaction.

Step 8: Verify Order Status and Proof

After payment, your backend should:

1. query the order status until it reaches a terminal state
2. retrieve the proof when the settlement flow is complete
3. store the proof if you need an auditable delivery record

For DELEGATE flows, do not treat payment confirmation alone as final business success if callback execution is still pending. Wait for the status that confirms the delegated settlement and callback path completed successfully.

DELEGATE Callback Setup

Use this section if your merchant uses DELEGATE mode.

A DELEGATE integration usually needs a callback contract and callback metadata before orders are accepted in the selected environment.

Typical setup flow:

1. Complete merchant onboarding and confirm the DELEGATE callback metadata requirements with the x402 operator or merchant portal.
2. Deploy the callback contract on the destination chain.
3. Get the deployed callback contract address.
4. Register callback metadata with the x402 operator:
   • merchant_id
   • chain_id
   • callback_contract
   • eip712_name, optional
   • eip712_version, optional
5. Wait for platform operations to review and approve the Callback Contract configuration. The callback contract does not take effect until approval is complete.
6. Confirm the authorized x402 caller for the target environment. For GOAT mainnet, use 0x211514377efE034E1E0410388cCE1a2bF10131F2; for GOAT testnet3, use 0xA58917dB2712F1c09D0078aeee1BA3ED8eD3565a, unless the x402 operator provides an updated address.
7. Authorize the caller on the callback contract if the contract enforces caller checks.
8. Create orders with the required callback calldata.
9. Test the payment and callback path end to end in the selected environment.

The callback contract should validate the caller, signature, nonce, deadline, amount, and business-specific payload before executing any sensitive action.

Fast Validation Checklist

Before launch, verify:

• the full flow works with the selected environment credentials
• order creation returns the expected x402 payload
• the client can sign or submit the required payment data
• payment reaches the expected destination
• backend status polling reaches the correct terminal state
• proof retrieval succeeds for completed flows
• supported tokens and chains match the merchant configuration
• API secrets are only available server-side

For DELEGATE flows, also verify:

• callback contract is deployed on the correct chain
• callback metadata is registered with the x402 operator
• authorized x402 caller is configured correctly
• callback calldata is generated correctly
• invalid caller, invalid signature, expired deadline, duplicate nonce, and amount mismatch are rejected
• business success is only shown after callback execution completes

Run the Reference Demo Locally

If you want to validate the full flow before wiring it into your own backend, the official demo app provides an end-to-end reference.

git clone https://github.com/GOATNetwork/x402.git
cd x402

cd goatx402-demo && pnpm install
cd ../goatx402-sdk-server-ts && pnpm install
cd ../goatx402-demo

GOATX402_MERCHANT_ID=your_merchant_id
GOATX402_API_URL=http://localhost:8286
GOATX402_API_KEY=your_api_key
GOATX402_API_SECRET=your_api_secret
PORT=3001

pnpm dev

curl http://localhost:3001/api/health
curl http://localhost:3001/api/config

Use AI to Scaffold the Integration

You can use the following prompt with an AI coding assistant to scaffold an x402 integration quickly. Replace the placeholder environment values with your own merchant configuration.

Add x402 payments to my backend and frontend.

Use the selected x402 environment configuration:
- API base URL: <GOATX402_API_URL>
- Merchant ID: <GOATX402_MERCHANT_ID>
- API key and secret must stay server-side.
- For GOAT testnet3, use chain ID 48816, RPC https://rpc.testnet3.goat.network, explorer https://explorer.testnet3.goat.network, and merchant portal https://x402-merchant-lx58aabp0r.testnet3.goat.network/merchants.
- For production, use https://x402-api.goat.network as the x402 API base URL.

Implementation requirements:
1. Add backend environment variables for GOATX402_API_URL, GOATX402_API_KEY, GOATX402_API_SECRET, and GOATX402_MERCHANT_ID.
2. Never expose GOATX402_API_SECRET to the frontend.
3. Fetch merchant configuration from GET /merchants/{merchant_id}.
4. Use the merchant config wallets as the source of truth for supported payment routes.

Expected merchant config shape:

{
  "merchant_id": "ENS_ON_GOAT",
  "enabled": true,
  "receive_type": "DELEGATE",
  "wallets": [
    {
      "address": "0x...",
      "chain_id": 48816,
      "token_symbol": "TUSDT",
      "token_contract": "0x...",
      "decimals": 18
    }
  ]
}

5. Build supported payment routes from wallets:
   - chain_id
   - token_symbol
   - token_contract
   - decimals, if present
6. If token decimals are not returned, resolve them from local token metadata or by reading the ERC-20 decimals method.
7. Do not show a merchant route unless the frontend has wallet metadata for that chain: chain ID, chain name, RPC URL, native currency, and explorer.
8. Create orders from the backend using the final x402 API fields for the selected environment. Common fields are:
   - dapp_order_id
   - chain_id
   - token_symbol
   - token_contract
   - from_address
   - amount_wei
   - callback_calldata, only for DELEGATE flows
9. If merchant_id is bound to the API credentials instead of accepted in the create-order body, keep it in backend configuration and do not send it in the request body.
10. If the app uses internal names such as settlementChainId, settlementTokenSymbol, or settlementTokenContract, map them to chain_id, token_symbol, and token_contract before calling x402.
11. Treat HTTP 402 payment-required responses as expected protocol responses. Do not handle them as generic backend failures.
12. Poll order status and retrieve proof after payment.
13. For DELEGATE flows, payment confirmed is not enough. Wait for the terminal status that confirms delegated settlement and callback execution.

For DIRECT mode:
- Use x402 for payment-gated delivery.
- Unlock the protected response only after the order reaches the expected paid/completed state.

For DELEGATE mode:
- Do not pass the callback contract in each order.
- The callback contract is registered through merchant callback metadata.
- Each order only includes callback_calldata.
- callback_calldata should encode the per-order business action.
- Do not put API secrets or trusted business decisions in callback_calldata.
- Validate callback_calldata again in the backend or callback contract.
- Wait for delegated settlement and callback execution before marking the user-facing action complete.
- Authorize the x402 caller for the target environment:
  - GOAT mainnet: 0x211514377efE034E1E0410388cCE1a2bF10131F2
  - GOAT testnet3: 0xA58917dB2712F1c09D0078aeee1BA3ED8eD3565a

Deliverables:
- Backend x402 client/helper
- Merchant config endpoint for the frontend
- Create-order endpoint
- Order status/proof endpoint
- Frontend chain metadata for every displayed payment route
- Frontend payment route selector
- Frontend payment flow UI
- Error handling for unsupported chain/token, missing chain metadata, expired order, failed payment, and callback failure
- A short README explaining required environment variables

Production Checklist

• Keep API credentials isolated on the backend; never ship GOATX402_API_SECRET to the client. API keys are optional for DIRECT Hosted QuickPay and required for programmatic x402 and the DELEGATE mode.
• Use https://x402-api.goat.network as the production base URL.
• Replace test merchant credentials with production merchant credentials.
• Confirm merchant receive type matches your integration mode.
• Monitor fee balance — insufficient balance blocks order creation.
• Implement bounded polling with retries and timeouts.
• Auto-cancel stale CHECKOUT_VERIFIED orders to reclaim reserved balance and fees.
• Retrieve and persist settlement proof when auditability is required.
• Log order IDs, payment status, and settlement status for support and debugging.

For DELEGATE integrations:

• Deploy and verify the callback contract before accepting production payments.
• Register the correct callback contract and any optional EIP-712 metadata required by your callback flow.
• Authorize the x402 caller before accepting production payments.
• Validate callback calldata, signature, nonce, deadline, amount, and destination action.
• Test callback success and callback failure paths end to end.

Next Steps

• Payment Modes
• API Reference
• Merchant Onboarding