# Tutorial — x402-print-mail From `git clone` to a paid call returning a real artifact, then to mainnet. ## 1. Install ```bash git clone https://github.com/nirholas/x402-print-mail cd x402-print-mail npm install ``` Node 18+ is required (the server uses the built-in `fetch`). ## 2. Configure (optional) ```bash cp .env.example .env ``` Every value already has a working default, so you can skip this entirely. The two you'll eventually want to change: ```bash PAY_TO_ADDRESS=0xYourEvmAddress # where USDC on Base lands SOLANA_PAY_TO_ADDRESS=YourSolanaAddress # where USDC on Solana lands ``` Left unset, the server uses the suite's own receive addresses and says so on startup: ``` note: using suite default payTo — set PAY_TO_ADDRESS/SOLANA_PAY_TO_ADDRESS to receive funds yourself ``` ### Live Lob rendering (optional) Create a free account at [lob.com](https://lob.com) and copy the **test** key from the dashboard: ```bash LOB_API_KEY=test_xxxxxxxxxxxxxxxxxxxxxxxx ``` `source` flips from `"fixture"` to `"lob"`, the proof comes from Lob's renderer, and `previewUrl` plus `thumbnails` are populated. `testMode` stays `true` — a test key never mails anything. Swapping in a `live_` key is the only way to make real paper move, and the server says so on every startup. ## 3. Run the server ```bash npm run dev ``` ``` x402-print-mail listening on http://localhost:4024 data source: fixture payment rails: evm base-sepolia → 0x40252CFDF8B20Ed757D61ff157719F33Ec332402 solana solana → WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW paid routes: POST /letters $0.05 POST /postcards $0.03 free routes: GET /health, GET /.well-known/x402 ``` Check it's alive — `/health` is free: ```bash curl -s http://localhost:4024/health ``` ## 4. Your first 402 Call a paid route with no payment: ```bash curl -i -X POST http://localhost:4024/letters \ -H 'Content-Type: application/json' \ -d '{"to":{"name":"Dana Reyes","addressLine1":"1600 Pennsylvania Ave NW","addressCity":"Washington","addressState":"DC","addressZip":"20500"},"from":{"name":"Acme Robotics","addressLine1":"215 Clayton St","addressCity":"San Francisco","addressState":"CA","addressZip":"94117"},"body":"Dear Dana,\n\nYour order shipped today.\n\nSincerely,\nAcme"}' ``` You get `HTTP/1.1 402 Payment Required` and a body listing **both** rails: ```json { "x402Version": 1, "error": "X-PAYMENT header is required", "accepts": [ { "scheme": "exact", "network": "base-sepolia", "maxAmountRequired": "50000", "resource": "http://localhost:4024/letters", "description": "Send a physical letter and get the printed proof back in the response.", "mimeType": "application/json", "payTo": "0x40252CFDF8B20Ed757D61ff157719F33Ec332402", "maxTimeoutSeconds": 60, "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "extra": { "name": "USDC", "version": "2" } }, { "scheme": "exact", "network": "solana", "maxAmountRequired": "50000", "resource": "http://localhost:4024/letters", "description": "Send a physical letter and get the printed proof back in the response.", "mimeType": "application/json", "payTo": "WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW", "maxTimeoutSeconds": 60, "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "extra": { "name": "USD Coin", "decimals": 6, "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4", "amount": "50000" } } ] } ``` Read it as: *"pay $0.05 of USDC to one of these two addresses, on whichever chain you prefer, then ask again."* `maxAmountRequired` is in atomic units — USDC has 6 decimals, so `"50000"` is `$0.05`. ## 5. Pay for it ### EVM (Base) — `x402-fetch` The included client does the whole dance. Give it a funded key: ```bash # A base-sepolia key with testnet USDC. Faucet: https://faucet.circle.com export PRIVATE_KEY=0xYourTestnetPrivateKey npm run client ``` `wrapFetchWithPayment` catches the 402, signs an EIP-3009 USDC authorization for the amount quoted, and replays the request with the `X-PAYMENT` header. You never write the retry loop. ### Solana A Solana wallet signs a serialized SPL transfer rather than typed data, so the server exposes two helpers: ```bash # 1. Ask for the transaction that satisfies the Solana accept curl -s -X POST 'http://localhost:4024/api/x402-checkout?action=prepare' \ -H 'content-type: application/json' \ -d '{"accept": , "buyer": ""}' # → { "tx_base64": "...", "recent_blockhash": "..." } # 2. Sign tx_base64 with your wallet, then wrap it into an X-PAYMENT header curl -s -X POST 'http://localhost:4024/api/x402-checkout?action=encode' \ -H 'content-type: application/json' \ -d '{"accept": , "signed_tx_base64": "", "resource_url": ""}' # → { "x_payment": "..." } ``` Then retry the original request with `X-PAYMENT: `. In a browser, [`@three-ws/x402-payment-modal`](https://www.npmjs.com/package/@three-ws/x402-payment-modal) does all of this from a single `