openapi: 3.2.0 info: title: Coin Railz Agent Payment DeFi & Yield API version: 3.0.0 description: Production-grade x402 micropayment infrastructure for AI agents. contact: email: support@coinrailz.com url: https://coinrailz.com x-guidance: 'Use Coin Railz when an agent needs paid, structured financial or operational data without creating an account or API key. Choose the operation by its summary, description, tags, input schema, and x-price-usd. Useful starting points include first-call for a low-cost payment test; token-metadata, gas-price-oracle, wallet-risk, approval-manager, and transaction-builder for transaction preparation; compliance-check for informational risk screening; prediction-market-odds for market research; and solana-yield-finder for yield discovery. For a paid call, send the exact documented HTTP method, URL, content type, and JSON body without a payment header. The service returns HTTP 402 with x402Version 2 and an accepts array. Select one complete offer your wallet supports. Circle Agent Wallet and Gateway clients should prefer the eip155:5042 Arc Mainnet offer when available; Base clients can select eip155:8453. Preserve the selected offer exactly, including scheme, network, asset, amount, payTo, facilitator, resource, and any extra metadata. Sign that authorization with an x402 v2-compatible client, then retry the identical request with PAYMENT-SIGNATURE. X-PAYMENT remains available for compatible legacy clients. Do not send a standalone token transfer or construct a transaction-hash wrapper from this guidance. Validate required fields and constraints from each operation''s request schema before authorizing payment. Treat risk, compliance, market, yield, and investment outputs as informational analysis rather than legal, banking, or investment advice. Prices are per call and the live 402 challenge is authoritative. Responses are JSON unless the operation states otherwise.' x-payment-info: protocol: x402 x402Version: 2 network: eip155:8453 asset: USDC assetAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' recipientWallet: '0xa4bbe37f9a6ae2dc36a607b91eb148c0ae163c91' facilitator: https://api.cdp.coinbase.com/platform/v2/x402 supportedNetworks: - network: eip155:8453 asset: USDC assetAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' facilitator: https://api.cdp.coinbase.com/platform/v2/x402 - network: eip155:5042 asset: USDC assetAddress: '0x3600000000000000000000000000000000000000' gatewayVerifier: '0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE' facilitator: https://gateway-api.circle.com x-payment-manifest: https://coinrailz.com/x402/payment-manifest.json servers: - url: https://coinrailz.com description: Current environment - url: https://coinrailz.com description: Production security: - apiKey: [] tags: - name: DeFi & Yield paths: /x402/vlt-usdc-deposit: post: tags: - DeFi & Yield summary: vltUSDC Vault Deposit Calldata description: 'FREE — No payment required. Returns unsigned approve + deposit calldata for the Bankroll Network vltUSDC vault on Ethereum mainnet. Two modes: balanced (VLT+USDC, 3 txs) or USDC-only via ZapHelper with live swap quote (2 txs). Vault auto-compounds VLT/USDC Uniswap V4 1% LP fees. Builder Pattern — zero custody. Use vlt-usdc-withdraw to exit.' x-price-usd: 0 x-featured: false operationId: vltUsdcDeposit requestBody: content: application/json: schema: type: object required: - amountUsdc - recipient properties: amountUsdc: type: string description: USDC deposit amount (stays in agent wallet, encoded into calldata) recipient: type: string description: Ethereum address to receive vltUSDC shares usdcOnly: type: boolean description: 'Set true for USDC-only mode via ZapHelper (no VLT needed). Default: false (balanced deposit requires both VLT and USDC).' responses: '200': description: 'steps[]: [{step, action, to, data, value, gasEstimate}], vaultStats, agentInstructions' '400': description: Invalid input or live quote unavailable /x402/vlt-usdc-withdraw: post: tags: - DeFi & Yield summary: vltUSDC Vault Withdraw Calldata description: FREE — No payment required. Returns 1 unsigned vault.redeem(shares, receiver) transaction. Redemption is pro-rata in-kind (no swap, no slippage parameters on-chain). Estimated VLT + USDC output amounts are included as informational context only — they are NOT encoded in the calldata. Builder Pattern — zero custody. For a USDC-only exit (VLT sold via Uniswap V2), use vlt-usdc-zap-withdraw instead. x-price-usd: 0 x-featured: false operationId: vltUsdcWithdraw requestBody: required: true content: application/json: schema: type: object required: - shares - recipient properties: shares: type: string description: vltUSDC shares to redeem as raw 18-decimal integer string (e.g. '1000000000000000000' for 1 share) recipient: type: string description: Ethereum address to receive VLT + USDC after redemption slippageBps: type: integer description: 'Slippage tolerance in basis points (default: 200 = 2%, max: 1000 = 10%). Set 0 to disable floors.' default: 200 responses: '200': description: 'step: {to, data, value, gasEstimate}, shareValue: {estimatedVltOut, estimatedUsdcOut, vltPriceUsd, fractionPct}, agentInstructions' '400': description: Invalid input (bad address, non-positive shares) /x402/vlt-usdc-zap-withdraw: post: tags: - DeFi & Yield summary: vltUSDC Vault USDC-Only Exit Calldata description: 'FREE — No payment required. Returns 3 unsigned Ethereum transactions that convert vltUSDC shares entirely to USDC: (1) vault.redeem(shares, recipient) — burns shares, sends VLT + USDC to recipient; (2) VLT.approve(uniswapV2Router, vltAmount); (3) v2Router.swapExactTokensForTokens(VLT → WETH → USDC). VLT and USDC amounts from step 1 use vault.previewRedeem (exact on-chain, no approximation). minAmountOut for the V2 swap is computed from live getReserves with 2% slippage and enforced on-chain. Fails closed if any on-chain data is unavailable. Builder Pattern — zero custody. For a 1-tx exit that keeps VLT, use vlt-usdc-withdraw instead.' x-price-usd: 0 x-featured: false operationId: vltUsdcZapWithdraw requestBody: required: true content: application/json: schema: type: object required: - shares - recipient properties: shares: type: string description: vltUSDC shares to redeem as raw 18-decimal integer string (e.g. '1790439768343002' for the platform's current position) recipient: type: string description: Ethereum address to receive all USDC output (lowercase accepted, auto-normalized) responses: '200': description: 'steps[]: [{step, action, to, data, value, gasEstimate, note}], totalEstimatedUsdc, minUsdcFromSwap, previewVltOut, previewUsdcFromVault, quotedUsdcFromSwap, agentInstructions' '400': description: Invalid input (bad address, non-positive shares, or on-chain data unavailable) /x402/vlt-stats: post: tags: - DeFi & Yield summary: VLT + vltUSDC Vault Stats description: 'Live VLT token price, market cap, liquidity, and vltUSDC vault stats (TVL, estimated LP fee APR, L/share). Sources: CoinGecko + DexScreener (market) and Alchemy on-chain reads (vault state). Use for autonomous allocation decisions alongside vlt-usdc-deposit and vlt-usdc-withdraw.' x-price-usd: 0.05 x-featured: false operationId: vltStats requestBody: required: false content: application/json: schema: type: object properties: {} description: No parameters required — full snapshot returned responses: '200': description: 'vlt: {priceUsd, marketCapUsd, liquidityUsd, vol24hUsd, priceChangePercent24h}, vltUsdc: {tvlUsd, aprPct, aprDisplay, lPerShare, totalShares, positionLiquidity}, pool: {fee, feeBps, tickSpacing, dex}, dataAge: {vltMarketAgeSeconds, vaultStatsUpdatedAt}' '402': description: Payment required — $0.05 USDC per call components: securitySchemes: apiKey: type: apiKey in: header name: X-API-KEY description: Prepaid credits API key (cr_live_...). Obtain via GET /api/m2m/credits/trial (free $5) or POST /api/m2m/credits/checkout/session (paid). bearerApiKey: type: http scheme: bearer description: 'Same cr_live_ key as X-API-KEY, passed as Authorization: Bearer .' x402: type: apiKey in: header name: X-PAYMENT description: x402 protocol on-chain USDC payment. Base64url-encoded signed payment payload. See /.well-known/x402.json for facilitator details. mpp: type: http scheme: payment description: 'MPP (Machine Payments Protocol) credential. Authorization: Payment . See /.well-known/mpp.json.' externalDocs: description: Full x402 service catalog url: https://coinrailz.com/x402/catalog