# 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