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