proxmox/x402-api/README.md

# 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