x402 Developer Quick Start

This guide is for builders who want a first working x402 integration before optimizing the full merchant setup.

Before You Start

Make sure you have:

a backend where secrets can stay server-side
merchant onboarding credentials for your x402 environment
a clear choice of whether you only need gated delivery or callback-enabled settlement

Step 1: Get the Integration Resources

Use the official repository when you want the reference implementation:

Clone the x402 repository

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

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

Step 2: Configure Backend Credentials

.env

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

GOATX402_API_SECRET must stay on the server. Do not expose it in frontend bundles or public environment variables.

Step 3: Create the First Order

At a minimum, your backend should call the order-creation endpoint and be prepared for HTTP 402 as the normal success path.

Minimal order lifecycle

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

Step 4: Decide How the User Pays

Use DIRECT if the user should pay the merchant address directly and no callback flow is needed.
Use DELEGATE if settlement should go through delegated infrastructure and may trigger contract logic.

See Payment Modes for the full decision guide.

Step 5: Verify the Order Status and Proof

After payment:

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

Fast Validation Checklist

order creation returns the expected x402 payload
the client can sign the required authorization data
payment reaches the correct destination address
backend status polling reaches a terminal state
proof retrieval succeeds for completed flows

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.

Clone and install dependencies

Clone and install

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

Configure the demo backend

Create goatx402-demo/.env:

goatx402-demo/.env

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

GOATX402_MERCHANT_ID, GOATX402_API_KEY, and GOATX402_API_SECRET are onboarding credentials for your x402 environment. Replace GOATX402_API_URL with your hosted base URL if you are not running Core locally — for production, use https://api.x402.goat.network.

Run the demo

Start the demo

pnpm dev

Verify backend health and config

Smoke test the running backend

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

Production Checklist

Keep API credentials isolated on the backend; never ship GOATX402_API_SECRET to the client.
Use https://api.x402.goat.network as the production base URL.
Monitor fee balance — insufficient balance blocks order creation.
Auto-cancel stale CHECKOUT_VERIFIED orders to reclaim reserved balance and fees.
Implement bounded polling with retries and timeouts.
Retrieve and persist settlement proof for auditability.
For DELEGATE flows, test calldata-signature and callback paths end to end.