dbd517b279
- Update dbis_core, cross-chain-pmm-lps, explorer-monorepo, metamask-integration, pr-workspace/chains - Omit embedded publish git dirs and empty placeholders from index Made-with: Cursor
64 lines
3.2 KiB
Markdown
64 lines
3.2 KiB
Markdown
# x402 API (Chain 138–ready)
|
||
|
||
Minimal Express API that accepts [x402](https://portal.thirdweb.com/x402) payments using thirdweb’s `settlePayment` and facilitator. **Production target:** Chain **138** with **cUSDT V2 / cUSDC V2** (ERC-2612 / ERC-3009). **Default demo:** Arbitrum Sepolia + USDC so you can run the server without a permit-capable Chain 138 token in `.env`.
|
||
|
||
## Prerequisites
|
||
|
||
- Node.js 18+
|
||
- [thirdweb](https://portal.thirdweb.com) account and **secret key** (Dashboard → Settings → API Keys)
|
||
- A server wallet address (EOA) that will receive payments
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
cd x402-api
|
||
cp .env.example .env
|
||
# Edit .env: set THIRDWEB_SECRET_KEY and SERVER_WALLET_ADDRESS
|
||
npm install
|
||
```
|
||
|
||
## Run
|
||
|
||
```bash
|
||
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](../docs/04-configuration/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=true` and `SERVER_WALLET_ADDRESS` in `.env`. Optional: `CHAIN_651940_RPC_URL`. Local verification is used; `THIRDWEB_SECRET_KEY` is not required for the Alltra path.
|
||
- **Chain 138:** Set `X402_USE_CHAIN_138=true` and optionally `RPC_URL_138`. Use **V2** compliant USD token addresses from [CHAIN138_X402_TOKEN_SUPPORT.md](../docs/04-configuration/CHAIN138_X402_TOKEN_SUPPORT.md) in the API’s price config (V1 cUSDT/cUSDC are not x402-capable).
|
||
|
||
Verification script for token support:
|
||
|
||
```bash
|
||
./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](https://portal.thirdweb.com/x402/server)
|
||
- [CHAIN138_X402_TOKEN_SUPPORT.md](../docs/04-configuration/CHAIN138_X402_TOKEN_SUPPORT.md) – Which Chain 138 tokens support permit/ERC-3009
|
||
- [CHAIN138_TOKEN_ADDRESSES.md](../docs/11-references/CHAIN138_TOKEN_ADDRESSES.md) – Token addresses on Chain 138
|