Elsa x402 Facilitator

Verify a Payment

Verify a payment authorization before executing it on-chain.

Request

# Verify payment authorization
curl -X POST verify \
  -H "Content-Type: application/json" \
  -d '{
    "x402Version": 1,
    "paymentPayload": {...},
    "paymentRequirements": {...}
  }'

200 OK - Valid

{
  "scheme": "exact",
  "network": "base",
  "isValid": true,
  "payer": "0x..."
}

200 OK - Invalid

{
  "scheme": "exact",
  "network": "base",
  "isValid": false,
  "invalidReason": "invalid_authorization_signature"
}

400 Bad Request

invalid character 'x' looking for beginning of value

500 Internal Server Error

internal server error

Settle a Payment

Execute a verified payment authorization on-chain.

Request

# Execute payment on-chain
curl -X POST settle \
  -H "Content-Type: application/json" \
  -d '{
    "x402Version": 1,
    "paymentPayload": {...},
    "paymentRequirements": {...}
  }'

200 OK - Success

{
  "scheme": "exact",
  "network": "base",
  "success": true,
  "transaction": "0x..."
}

200 OK - Failed

{
  "scheme": "exact",
  "network": "base",
  "success": false,
  "errorReason": "invalid_authorization_signature"
}

400 Bad Request

invalid character 'x' looking for beginning of value

500 Internal Server Error

internal server error

Supported Networks

Get a list of supported x402 versions, schemes, and networks.

Request

# List supported networks
curl -X GET supported

200 OK

{
  "kinds": [
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "base-sepolia"
    },
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "base"
    },
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "soneium"
    },
    {
      "x402Version": 1,
      "scheme": "exact",
      "network": "robinhood"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:84532"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:8453"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:1868"
    },
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "eip155:4663"
    }
  ]
}

Builder Codes (ERC-8021)

This facilitator stamps ERC-8021 builder-code attribution onto each settlement's calldata, so onchain payments can be credited to the parties involved. Three codes can be attached — each must match ^[a-z0-9_]{1,32}$:

For Sellers

Declare your app code (a) in the 402 PaymentRequired response. It is carried through the payment and recorded onchain when this facilitator settles. See CDP · Builder Codes · For Sellers.

// x402 v2 route config (@x402/express)
import {
  BUILDER_CODE,
  declareBuilderCodeExtension,
} from '@x402/extensions/builder-code';

// attach to the protected route's extensions
extensions: { [BUILDER_CODE]: declareBuilderCodeExtension('your_app_code') }

For Buyers

Attach your service code (s) to the payments your client makes.

// x402 v2 client (@x402/axios or @x402/fetch)
import { BuilderCodeClientExtension } from '@x402/extensions/builder-code';

client.registerExtension(new BuilderCodeClientExtension('your_service_code'));

The wallet code (w) is added by this facilitator at settlement automatically — buyers and sellers don't need to set it.