b3a8fe4496
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- Config, docs, scripts, and backup manifests - Submodule refs unchanged (m = modified content in submodules) Made-with: Cursor
61 lines
2.6 KiB
Markdown
61 lines
2.6 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. 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](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 138 and token support
|
||
|
||
x402 requires the payment token to support **ERC-2612 permit** or **ERC-3009**. Currently, cUSDT and cUSDC on Chain 138 do **not** support these (see [CHAIN138_X402_TOKEN_SUPPORT.md](../docs/04-configuration/CHAIN138_X402_TOKEN_SUPPORT.md)).
|
||
|
||
- **Default:** The API uses **Arbitrum Sepolia** and default USDC (`price: "$0.01"`) so you can test end-to-end without Chain 138.
|
||
- **Chain 138:** Set `X402_USE_CHAIN_138=true` and optionally `RPC_URL_138` in `.env` once a Chain 138 token has permit/ERC-3009 (e.g. after adding ERC20Permit to compliant tokens and redeploying). The server then uses the custom Chain 138 definition and the configured token for settlement.
|
||
|
||
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_CHAIN_138` | No | `true` to use Chain 138 (default `false`) |
|
||
| `RPC_URL_138` | No | Chain 138 RPC when using Chain 138 (default public RPC) |
|
||
| `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
|