{"title":"How to Do Business with Coin Railz","version":"1.0.0","lastUpdated":"2026-03-17","summary":"Step-by-step guide for AI agents to purchase blockchain analytics and trading services via x402 micropayments or prepaid credits.","recommended_next_step":{"action":"claim_free_trial","description":"Get a FREE $5 trial API key instantly — no payment, no crypto wallet, no account. Works on all 80 services. 1 per IP per 7 days.","endpoint":"https://coinrailz.com/api/m2m/credits/trial","method":"GET","headers":{"Accept":"application/json"},"successResponse":{"apiKey":"cr_live_...","credits":5,"expiresIn":"7 days","note":"SAVE apiKey — returned once only"},"usageHeaders":{"primary":"X-API-KEY: cr_live_...","alternative":"Authorization: Bearer cr_live_..."},"expected_time":"instant","next_step_after_trial":"POST https://coinrailz.com/api/m2m/credits/purchase to purchase a paid plan ($5/$10/$25/$100)"},"quickStart":{"description":"Three paths to get started — free trial (fastest), card payment, or on-chain USDC","recommendedPath":"freeTrial","paths":{"freeTrial":{"label":"Free Trial (Fastest — no payment, no crypto)","steps":[{"step":1,"action":"Claim your free trial API key","endpoint":"https://coinrailz.com/api/m2m/credits/trial","method":"GET","headers":{"Accept":"application/json"},"rateLimit":"1 per IP per 7 days","successResponse":{"apiKey":"cr_live_...","credits":5,"expiresIn":"7 days"},"warning":"SAVE the apiKey — shown once only"},{"step":2,"action":"Call any service with your trial key","description":"Pass the key as X-API-KEY header on any /x402/* endpoint. $5 in credits (~80-100 calls).","curlExample":"curl -X POST https://coinrailz.com/x402/gas-price-oracle -H 'X-API-KEY: cr_live_...' -H 'Content-Type: application/json' -d '{}'","catalogUrl":"https://coinrailz.com/x402/catalog"}]},"cardPayment":{"label":"Card Payment (Recommended — no crypto required)","steps":[{"step":1,"action":"Create a Stripe PaymentMethod","description":"Use Stripe.js or the Stripe API to tokenize a card. Returns a pm_... PaymentMethod ID.","stripeDocsUrl":"https://stripe.com/docs/api/payment_methods/create"},{"step":2,"action":"Purchase credits and get your API key","endpoint":"https://coinrailz.com/api/m2m/credits/purchase","method":"POST","body":{"paymentMethodId":"pm_...","amountUsd":10,"idempotencyKey":"<uuid-v4-string>"},"idempotencyNote":"Unique string per purchase (min 8 chars, UUID v4 recommended). Reuse safely on network retry.","tiers":[{"amountUsd":5,"calls":"~80-100 service calls","note":"Try it — no commitment"},{"amountUsd":10,"calls":"~200 service calls"},{"amountUsd":25,"calls":"~500 service calls","recommended":true},{"amountUsd":100,"calls":"~2,000 service calls"}],"successResponse":{"apiKey":"cr_live_...","keyPrefix":"cr_live","creditsAdded":200,"newBalance":200},"errorCodes":{"400":"Invalid paymentMethodId (must start with pm_) or idempotencyKey too short","409":"Purchase already processed for this idempotencyKey — use a new key for a new purchase","429":"Rate limit: 5 purchases per IP per hour — retry after 1 hour"},"warning":"SAVE the apiKey from the response — shown once only"},{"step":3,"action":"Call any service with your API key","description":"Pass the key as X-API-KEY header on any /x402/* endpoint. Credits deducted per call.","curlExample":"curl -X POST https://coinrailz.com/x402/gas-price-oracle -H 'X-API-KEY: cr_live_...' -H 'Content-Type: application/json' -d '{\"chains\":[\"base\"]}'","catalogUrl":"https://coinrailz.com/x402/catalog"}]},"onChainUsdc":{"label":"On-Chain USDC via x402 (crypto-native)","steps":[{"step":1,"action":"Get a Wallet","description":"Create a free agent wallet or use your own EVM wallet with USDC on Base","endpoint":"https://coinrailz.com/x402/wallet/free","method":"POST","example":{"agentId":"your-agent-id","purpose":"payments"}},{"step":2,"action":"Fund with USDC","description":"Send USDC to your wallet on Base mainnet (Chain ID 8453)","network":"Base Mainnet","chainId":8453,"token":{"symbol":"USDC","address":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","decimals":6},"bridges":[{"name":"Base Bridge","url":"https://bridge.base.org"},{"name":"Across Protocol","url":"https://app.across.to"},{"name":"Stargate","url":"https://stargate.finance"}]},{"step":3,"action":"Make Your First Paid Call","description":"Start with the Golden Path endpoint — $0.05 USDC, lowest price on platform. Receive 402, pay via facilitator, retry with X-PAYMENT header.","facilitator":{"evm":"https://api.cdp.coinbase.com/platform/v2/x402","solana":"https://x402.dexter.cash"},"goldenPathEndpoint":"https://coinrailz.com/x402/first-call","price":"$0.05 USDC","chainsAccepted":["Base (eip155:8453)","Solana mainnet"],"curlExample":"curl -X POST https://coinrailz.com/x402/first-call -H 'Content-Type: application/json' -H 'X-PAYMENT: <tx_hash>' -d '{}'","pythonExample":"import httpx\nresp = httpx.post('https://coinrailz.com/x402/first-call', headers={'X-PAYMENT': tx_hash}, json={})\nprint(resp.json())"}]}}},"goldenPath":{"description":"START HERE. The canonical first payment endpoint for any new agent integrating with Coin Railz.","endpoint":"https://coinrailz.com/x402/first-call","method":"POST","price":"$0.05 USDC","amountMicroUSDC":50000,"chainsAccepted":["Base (eip155:8453)","Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)"],"onSuccess":"Returns sessionId, payment receipt, and 3 next-service templates with executable curl examples"},"walletOptions":{"description":"Three ways to get a wallet for payments","options":[{"id":"free-wallet","name":"Free Agent Wallet","description":"Instant wallet creation via Coinbase CDP - no cost, ready in seconds","endpoint":"https://coinrailz.com/x402/wallet/free","method":"POST","cost":"Free","features":["Instant creation","CDP-managed","Base mainnet ready"]},{"id":"instant-agent-wallet","name":"Premium Agent Wallet","description":"Enhanced wallet with additional features via x402 payment","endpoint":"https://coinrailz.com/x402/instant-agent-wallet","method":"POST","cost":"$1.00 USDC","features":["Priority support","Analytics dashboard","Multi-chain ready"]},{"id":"self-custody","name":"Self-Custody Wallet","description":"Use any existing EVM wallet (MetaMask, Rainbow, etc.)","requirements":["EVM wallet with Base network support","USDC on Base mainnet"],"cost":"Free (you manage keys)"}]},"paymentMethods":{"description":"Multiple ways to pay for services","methods":[{"id":"x402","name":"x402 Micropayments","description":"Pay-per-call USDC payments via HTTP 402 protocol","howItWorks":["1. Make request to any service endpoint","2. Receive 402 Payment Required response with payment details","3. Sign and submit USDC payment via facilitator","4. Retry request with X-PAYMENT header containing tx hash","5. Receive service response"],"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402","platformWallet":"0xa4bbe37f9a6ae2dc36a607b91eb148c0ae163c91","network":"eip155:8453","token":"USDC"},{"id":"credits","name":"Prepaid Credits","description":"Buy credits in bulk for discounted access","endpoint":"https://coinrailz.com/api/credits","dashboard":"https://coinrailz.com/credits","benefits":["Volume discounts","No per-transaction signing","Usage tracking"]},{"id":"sdk","name":"SDK Integration","description":"Use our SDK packages for seamless payment handling","packages":{"npm":"@coinrailz/agent-payments","npmSolana":"@coinrailz/agent-payments-solana","python":"coinrailz","pythonSolana":"coinrailz-solana","docker":"tdnupe3/agent-payments"},"documentation":"https://coinrailz.com/docs/sdk"}]},"pricing":{"description":"Service pricing ranges from $0.05 to $10.00 USDC per call","pricingTiers":[{"tier":"Basic","range":"$0.05 - $0.25","examples":["ping","gas-price-oracle","fire-alerts","kalshi-markets","kalshi-search"]},{"tier":"Standard","range":"$0.25 - $1.00","examples":["multi-chain-balance","wallet-risk","trade-signals","kalshi-odds"]},{"tier":"Premium","range":"$1.00 - $5.00","examples":["instant-agent-wallet","verified-agent-identity"]},{"tier":"Enterprise","range":"$5.00 - $10.00","examples":["smart-contract-audit","compliance-consultation"]}],"fullCatalog":"https://coinrailz.com/x402/catalog","paymentDocs":"https://coinrailz.com/x402/payment-docs"},"troubleshooting":{"commonIssues":[{"issue":"402 Payment Required but payment not recognized","solutions":["Verify transaction was sent to correct wallet: 0xa4bbe37f9a6ae2dc36a607b91eb148c0ae163c91","Confirm transaction is on Base mainnet (not Ethereum or other chains)","Ensure payment is in USDC (not ETH or other tokens)","Wait for transaction confirmation (1-2 blocks)"]},{"issue":"Insufficient funds error","solutions":["Bridge USDC to Base via bridge.base.org or across.to","Minimum recommended balance: $5 USDC for testing","Consider buying prepaid credits for bulk usage"]},{"issue":"Wallet creation failed","solutions":["Use unique agentId for each wallet request","Check /x402/wallet/free endpoint is accessible","Contact support if issue persists"]}],"support":{"statusEndpoint":"https://coinrailz.com/x402/payment-status","documentation":"https://coinrailz.com/x402/payment-docs","contact":"support@coinrailz.com"}},"codeExamples":{"summary":"Copy-paste ready code. Fastest start: free trial key — no wallet, no crypto, instant.","python_free_trial":{"language":"python","runtime":"pip install httpx","description":"Recommended — free $5 trial key, works in 2 steps, no crypto required","code":"import httpx\n\n# Step 1: get your free trial API key (one per IP per 7 days)\nresp = httpx.get('https://coinrailz.com/api/m2m/credits/trial')\napi_key = resp.json()['apiKey']  # save this — shown once only\n\n# Step 2: call any service with your key\nresult = httpx.post('https://coinrailz.com/x402/gas-price-oracle',\n    headers={'X-API-KEY': api_key},\n    json={'chains': ['base', 'ethereum']})\nprint(result.json())"},"nodejs_free_trial":{"language":"javascript","runtime":"node (built-in fetch, Node 18+)","description":"Recommended — free $5 trial key, no crypto required","code":"// Step 1: get your free trial API key\nconst trialResp = await fetch('https://coinrailz.com/api/m2m/credits/trial');\nconst { apiKey } = await trialResp.json(); // save this — shown once only\n\n// Step 2: call any service\nconst result = await fetch('https://coinrailz.com/x402/gas-price-oracle', {\n  method: 'POST',\n  headers: { 'X-API-KEY': apiKey, 'Content-Type': 'application/json' },\n  body: JSON.stringify({ chains: ['base', 'ethereum'] })\n});\nconsole.log(await result.json());"},"python_x402_native":{"language":"python","runtime":"pip install x402 httpx","description":"Native x402 on-chain USDC payments — pay per call, no API key needed","code":"from x402.client import with_payment_handler\nimport httpx\n\n# Your EVM private key with USDC on Base mainnet\nPRIVATE_KEY = '0xYOUR_PRIVATE_KEY'\n\n# Wrap httpx client with automatic 402 payment handling\nclient = httpx.Client()\nwith_payment_handler(client, wallet_private_key=PRIVATE_KEY)\n\n# Now calls automatically pay the 402 challenge and retry\nresp = client.post('https://coinrailz.com/x402/gas-price-oracle', json={'chains': ['base']})\nprint(resp.json())  # $0.10 USDC deducted automatically"},"nodejs_x402_native":{"language":"javascript","runtime":"npm install x402 viem","description":"Native x402 on-chain USDC payments — pay per call, no API key needed","code":"import { wrapFetch } from 'x402/client';\nimport { privateKeyToAccount } from 'viem/accounts';\n\n// Your EVM private key with USDC on Base mainnet\nconst account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');\n\n// Wrap fetch with automatic 402 payment handling\nconst fetch402 = wrapFetch(fetch, account);\n\n// Calls automatically pay the 402 challenge and retry\nconst resp = await fetch402('https://coinrailz.com/x402/gas-price-oracle', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({ chains: ['base'] })\n});\nconsole.log(await resp.json());  // $0.10 USDC deducted automatically"},"manual_x402_flow":{"language":"python","runtime":"pip install httpx","description":"Manual x402 flow — understand what happens under the hood","code":"import httpx, json\n\nENDPOINT = 'https://coinrailz.com/x402/gas-price-oracle'\nFACILITATOR = 'https://api.cdp.coinbase.com/platform/v2/x402'\n\n# Step 1: probe — expect 402\nresp = httpx.post(ENDPOINT, json={})\nassert resp.status_code == 402\npayment_req = resp.json()\n# payment_req['accepts'] contains: scheme, network, maxAmountRequired, payTo, asset\n\n# Step 2: sign payment via CDP facilitator (requires CDP API key)\npay_resp = httpx.post(f'{FACILITATOR}/pay', json={\n    'paymentRequirements': payment_req['accepts'],\n    'wallet': {'privateKey': '0xYOUR_KEY'}\n})\nx_payment = pay_resp.json()['payment']\n\n# Step 3: retry with X-PAYMENT header\nfinal = httpx.post(ENDPOINT, headers={'X-PAYMENT': x_payment}, json={})\nprint(final.json())"},"curl_free_trial":{"language":"bash","description":"One-liner shell test — get trial key and make first call","code":"# Get free trial key\nAPI_KEY=$(curl -s https://coinrailz.com/api/m2m/credits/trial | python3 -c \"import sys,json; print(json.load(sys.stdin)['apiKey'])\")\n\n# Call any service\ncurl -s -X POST https://coinrailz.com/x402/gas-price-oracle \\\n  -H \"X-API-KEY: $API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"chains\":[\"base\"]}' | python3 -m json.tool"}},"links":{"agentRegistration":"https://coinrailz.com/.well-known/agent-registration.json","serviceCatalog":"https://coinrailz.com/x402/catalog","paymentDocs":"https://coinrailz.com/x402/payment-docs","agentCard":"https://coinrailz.com/.well-known/agent.json","agentCardA2A":"https://coinrailz.com/.well-known/agent-card.json","x402Manifest":"https://coinrailz.com/.well-known/x402.json","webmcpManifest":"https://coinrailz.com/.well-known/webmcp.json","awiManifest":"https://coinrailz.com/.well-known/awi.json","mppManifest":"https://coinrailz.com/.well-known/mpp.json","mcpIntegrationManifest":"https://coinrailz.com/.well-known/mcp-integration.json","mcpIntegrationGuide":"https://coinrailz.com/mcp-integration-guide","apiDiscovery":"https://coinrailz.com/api/discovery/resources","mcpServices":"https://coinrailz.com/mcp/services","freeWallet":"https://coinrailz.com/x402/wallet/free","credits":"https://coinrailz.com/credits","documentation":"https://coinrailz.com/docs","openapi":"https://coinrailz.com/openapi.json"}}