# Tutorial — x402-shipping From `git clone` to a paid call returning a real artifact, then to mainnet. ## 1. Install ```bash git clone https://github.com/nirholas/x402-shipping cd x402-shipping 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 carrier rates (optional) Get a **test** key from either provider — both are free and neither requires a payment method: ```bash SHIPPO_API_TOKEN=shippo_test_xxxxxxxxxxxx # https://goshippo.com # or EASYPOST_API_KEY=EZTKxxxxxxxxxxxxxxxx # https://easypost.com ``` `source` flips from `"fixture"` to `"shippo"` / `"easypost"`. `testMode` stays `true` as long as the key is a test key — the banner on startup tells you which mode you're in, loudly. ## 3. Run the server ```bash npm run dev ``` ``` x402-shipping listening on http://localhost:4023 data source: fixture payment rails: evm base-sepolia → 0x40252CFDF8B20Ed757D61ff157719F33Ec332402 solana solana → WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW paid routes: POST /rates $0.003 POST /label $0.02 free routes: GET /health, GET /.well-known/x402 ``` Check it's alive — `/health` is free: ```bash curl -s http://localhost:4023/health ``` ## 4. Your first 402 Call a paid route with no payment: ```bash curl -i -X POST http://localhost:4023/rates \ -H 'Content-Type: application/json' \ -d '{"from":{"street1":"215 Clayton St","city":"San Francisco","state":"CA","zip":"94117","country":"US"},"to":{"street1":"1600 Pennsylvania Ave NW","city":"Washington","state":"DC","zip":"20500","country":"US"},"parcel":{"length":10,"width":8,"height":4,"weight":32}}' ``` 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": "3000", "resource": "http://localhost:4023/rates", "description": "Rate-shop a parcel across every available carrier service.", "mimeType": "application/json", "payTo": "0x40252CFDF8B20Ed757D61ff157719F33Ec332402", "maxTimeoutSeconds": 60, "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "extra": { "name": "USDC", "version": "2" } }, { "scheme": "exact", "network": "solana", "maxAmountRequired": "3000", "resource": "http://localhost:4023/rates", "description": "Rate-shop a parcel across every available carrier service.", "mimeType": "application/json", "payTo": "WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW", "maxTimeoutSeconds": 60, "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "extra": { "name": "USD Coin", "decimals": 6, "feePayer": "2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4", "amount": "3000" } } ] } ``` Read it as: *"pay $0.003 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 `"3000"` is `$0.003`. ## 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:4023/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:4023/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 `