Coin Railz DeFi & Yield API

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 <key>.'
    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 <base64-credential>. See /.well-known/mpp.json.'
externalDocs:
  description: Full x402 service catalog
  url: https://coinrailz.com/x402/catalog