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.

For DELEGATE integrations, payment confirmation alone may not be the final application success state. The application should wait for delegated settlement and callback execution before marking the user-facing action as complete.

┌────────┐     ┌──────────┐     ┌─────────────┐     ┌───────────────┐
│        │  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

1. Complete merchant onboarding and confirm callback metadata

Before deploying the adapter, complete merchant onboarding and confirm the DELEGATE callback configuration with the x402 operator or merchant portal.

Confirm:

• the merchant account is approved for DELEGATE mode
• the destination chain_id where callbacks should execute
• the process for submitting the deployed callback_contract for platform review
• the authorized x402 caller for your target environment

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. Do not change these values for production orders unless you coordinate a versioned migration.

2. Deploy the adapter contract

Implement IX402CallbackAdapter from goatx402-contract. The adapter should validate the caller and callback payload before executing business logic.

Before deploying the adapter contract, confirm:

• The adapter is deployed on the destination chain where the callback should execute.
• The adapter points to the correct downstream business contract.
• If the callback flow uses EIP-712 domain fields, the adapter is configured with the same EIP-712 name and version used by the backend signing flow and operator records.
• The adapter has a clear owner or admin account for post-deployment configuration.
• The adapter can authorize the x402 caller for the target environment.
• Any constructor parameters are final and match the target environment.
• The adapter emits events for successful callbacks and rejected callbacks where possible.

After deployment:

1. Save the deployed adapter address as callback_contract.
2. Verify the contract on the explorer.

Do not accept production DELEGATE payments until the authorized x402 caller has been configured. If the caller is not authorized, payment settlement may complete, but the callback contract will reject execution.

3. Register the merchant callback

Register the callback metadata with the x402 operator:

• merchant_id: the merchant identifier issued during onboarding
• chain_id: the destination chain where the callback contract is deployed
• callback_contract: the adapter contract called after delegated settlement
• eip712_name, optional: the EIP-712 domain name expected by the callback signing flow
• eip712_version, optional: the EIP-712 domain version expected by the callback signing flow

After the Callback Contract configuration is submitted in the merchant portal, wait for platform operations to review and approve it. The callback contract does not take effect until approval is complete.

4. Align EIP-712 fields

If your callback flow uses eip712_name or eip712_version, ensure those values and the spender or settlement address used by the signing flow are configured consistently between the backend, callback contract, and operator records.

5. Authorize the x402 caller

Add the authorized x402 caller to your callback contract allowlist if your adapter restricts onX402Callback.

For GOAT mainnet, the current authorized x402 caller is:

0x211514377efE034E1E0410388cCE1a2bF10131F2

Always confirm the caller address with the x402 operator for your target environment before accepting production payments.

6. Create orders with callbackCalldata

When creating a DELEGATE order, include the callback calldata required by your adapter contract. The calldata should encode the business action that will be executed after settlement.

7. Test end to end

Validate the full flow: calldataSignRequest -> signature submit -> payment -> settlement -> callback -> proof.

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 token address, not only the amount.
• Validate the structure and bounds of calldata_.
• Reject expired callbacks if the payload includes a deadline.
• Reject replayed callbacks using nonce or order ID tracking.
• Bind the callback payload to the expected payer or order when applicable.
• Avoid trusting frontend-provided calldata without backend or contract validation.
• Use reentrancy guards if your callback invokes external contracts.
• Emit events for off-chain tracking and audit.

Production Notes

• Confirm the authorized x402 caller for the target environment.
• For GOAT mainnet, use 0x211514377efE034E1E0410388cCE1a2bF10131F2 unless the x402 operator provides an updated address.
• Register callback metadata before accepting production DELEGATE payments.
• Wait for platform operations to approve the Callback Contract configuration before accepting production DELEGATE payments.
• Authorize the x402 caller before accepting production DELEGATE payments.
• Treat payment confirmation and callback execution as separate states.
• Persist order IDs, callback results, and settlement proofs for auditability.

Related Guides

• Developer Quick Start
• API Reference
• Merchant Onboarding