x402 Payment Modes

x402 supports two main payment modes. The choice changes the settlement flow, the recipient model, and whether callback-enabled logic is available.

Why There Are Two Modes

• DIRECT keeps the flow simple for payment-gated delivery
• DELEGATE supports more advanced settlement and callback-triggered execution

DIRECT

DIRECT is the simpler model.

Best fit

• paid APIs
• content gating
• routes where the user should pay the merchant directly

Characteristics

• settlement target is the merchant address
• no callback contract flow
• simpler operator model
• lower integration complexity

DELEGATE

DELEGATE is the advanced model.

Best fit

• callback-enabled contract execution
• apps that need settlement orchestration
• payment-triggered minting, staking, or similar actions

Characteristics

• settlement target is delegated infrastructure
• callback-capable flow
• more moving pieces, but more flexibility

Comparison

How to Choose

Choose DIRECT if you need:

• the shortest path to production
• straightforward payment-gated access
• fewer backend and contract dependencies

Choose DELEGATE if you need:

• callback-enabled on-chain logic
• settlement orchestration through delegated infrastructure
• a flow where payment does more than unlock a response

DELEGATE Mode and Callback Contracts

DELEGATE mode enables payments to trigger on-chain logic — NFT mints, staking, DeFi actions — via a callback contract.

┌────────┐     ┌──────────┐     ┌─────────────┐     ┌───────────────┐
│        │  1  │          │  2  │             │  4  │               │
│  User  │ ──> │  DApp    │ ──> │  GOAT x402  │ ──> │ Your Adapter  │
│        │     │ Backend  │     │    Core     │     │   Contract    │
│        │ <── │          │ <── │             │ <── │               │
│        │  7  │          │  6  │             │  5  │               │
└────────┘     └──────────┘     └─────────────┘     └───────────────┘
     │                                 │
     │           3 (sign + pay)        │
     └─────────────────────────────────┘

1. User requests an action (e.g. mint NFT).
2. Backend creates an order with callbackCalldata.
3. User signs the EIP-712 payload and pays to the TSS address.
4. Core settles the payment and calls adapter.onX402Callback().
5. Your contract executes the business logic (mint, stake, etc.).
6. Core returns success or proof to the backend.
7. DApp confirms the result to the user.

Callback Interface

Your adapter contract must implement IX402CallbackAdapter:

interface IX402CallbackAdapter {
    function onX402Callback(
        address payer,
        address token,
        uint256 amount,
        bytes calldata calldata_
    ) external returns (bool success);
}

Integration Steps

Adapter Contract Security Checklist

• Only allow the authorized x402 Core address to call onX402Callback.
• Validate that payer is non-zero.
• Validate that amount matches the expected payment.
• Validate the structure and bounds of calldata_.
• Use reentrancy guards if your callback invokes external contracts.
• Emit events for off-chain tracking and audit.

Related Guides

• Developer Quick Start
• API Reference
• Merchant Onboarding