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 test wallet-based payments.

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 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 2: 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.

After approval, collect:

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

For 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 3: Configure Backend Credentials

Store x402 credentials on your backend.

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

Step 4: Create the First Order

Your backend should call the order creation endpoint and be prepared for HTTP 402 as the normal payment-required response.

Frontend -> backend create-order route
Backend -> x402 create order
x402 -> backend returns HTTP 402 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 data required by your callback contract when creating the order.

Step 5: 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 6: 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 production orders are accepted.

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 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.

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

Fast Validation Checklist

Before moving to production, verify:

• 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

Production Checklist

• Keep API credentials isolated on the backend.
• Use https://api.x402.goat.network as the production base URL.
• Confirm merchant receive type matches your integration mode.
• Implement bounded polling with retries and timeouts.
• Auto-cancel stale orders when appropriate.
• 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