e4c9dda0fd
- Marked submodules ai-mcp-pmm-controller, explorer-monorepo, and smom-dbis-138 as dirty to reflect recent changes. - Updated documentation to clarify operator script usage, including dotenv loading and task execution instructions. - Enhanced the README and various index files to provide clearer navigation and task completion guidance. Made-with: Cursor
x402 API (Chain 138–ready)
Minimal Express API that accepts x402 payments using thirdweb’s settlePayment and facilitator. Configured with a custom Chain 138 definition; by default uses Arbitrum Sepolia and USDC so you can test without a Chain 138 token that supports permit.
Prerequisites
- Node.js 18+
- thirdweb account and secret key (Dashboard → Settings → API Keys)
- A server wallet address (EOA) that will receive payments
Setup
cd x402-api
cp .env.example .env
# Edit .env: set THIRDWEB_SECRET_KEY and SERVER_WALLET_ADDRESS
npm install
Run
npm start
# or with auto-reload
npm run dev
- Health (no payment):
GET http://localhost:4020/health - Paid routes (402 until payment):
GET http://localhost:4020/api/premium,GET http://localhost:4020/api/paid
Clients must send payment authorization in the PAYMENT-SIGNATURE or X-PAYMENT header (e.g. using thirdweb’s useFetchWithPayment or equivalent).
Chain and token support
x402 requires the payment token to support ERC-2612 permit or ERC-3009 when using thirdweb facilitator. For Alltra (651940) we use local verification (no facilitator): server returns 402 + PAYMENT-REQUIRED, client pays USDC on 651940 and retries with PAYMENT-SIGNATURE + txHash; server verifies settlement on-chain. See X402_ALLTRA_ENDPOINT_SPEC.md.
- Default: The API uses Arbitrum Sepolia and default USDC so you can test without custom chains.
- Alltra (651940) + USDC: Set
X402_USE_ALLTRA=trueandSERVER_WALLET_ADDRESSin.env. Optional:CHAIN_651940_RPC_URL. Local verification is used;THIRDWEB_SECRET_KEYis not required for the Alltra path. - Chain 138: Set
X402_USE_CHAIN_138=trueand optionallyRPC_URL_138once a Chain 138 token has permit/ERC-3009 (see CHAIN138_X402_TOKEN_SUPPORT.md).
Verification script for token support:
./scripts/verify/check-chain138-token-permit-support.sh [RPC_URL]
Env reference
| Variable | Required | Description |
|---|---|---|
THIRDWEB_SECRET_KEY |
Yes | thirdweb API secret key |
SERVER_WALLET_ADDRESS |
Yes | Address that receives x402 payments |
X402_USE_ALLTRA |
No | true for Alltra (651940) USDC + local verification (default false) |
X402_USE_CHAIN_138 |
No | true to use Chain 138 (default false) |
RPC_URL_138 |
No | Chain 138 RPC when using Chain 138 (default public RPC) |
CHAIN_651940_RPC_URL |
No | Alltra RPC when X402_USE_ALLTRA=true (default mainnet-rpc.alltra.global) |
PORT |
No | Server port (default 4020) |
References
- thirdweb x402 – Server
- CHAIN138_X402_TOKEN_SUPPORT.md – Which Chain 138 tokens support permit/ERC-3009
- CHAIN138_TOKEN_ADDRESSES.md – Token addresses on Chain 138