Coin Railz Execution API

openapi: 3.2.0
info:
  title: Coin Railz Agent Payment Execution 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: Execution
  description: Transaction building and wallet services
paths:
  /x402/transaction-builder:
    post:
      tags:
      - Execution
      summary: Transaction Builder
      description: 'Encode and prepare any EVM transaction: ABI encoding, calldata construction, gas estimation, and nonce lookup for Ethereum, Base, Arbitrum, and Optimism.'
      x-price-usd: 0.3
      operationId: transactionBuilder
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - fromAddress
              - toAddress
              - chain
              properties:
                fromAddress:
                  type: string
                toAddress:
                  type: string
                chain:
                  type: string
                value:
                  type: string
                  description: Value in wei
                data:
                  type: string
                  description: Transaction data (hex)
      responses:
        '200':
          description: Encoded transaction ready for signing
        '402':
          description: Payment Required
      x-featured: false
  /x402/payment-processing:
    post:
      tags:
      - Execution
      summary: Payment Processing
      description: Process USDC payments across EVM chains with automatic routing and fee optimization. Returns transaction receipt, confirmed amount, and destination chain confirmation.
      x-price-usd: 0.5
      operationId: paymentProcessing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - amount
              - recipient
              - chain
              properties:
                amount:
                  type: string
                recipient:
                  type: string
                chain:
                  type: string
      responses:
        '200':
          description: Payment processed
        '402':
          description: Payment Required
      x-featured: false
  /x402/contract-scan:
    post:
      tags:
      - Execution
      summary: Contract Security Scanner
      description: Smart contract security scan returning a safety score (0-100) and structured vulnerability findings (reentrancy, overflow, access control, logic flaws) for any deployed EVM contract address.
      x-price-usd: 1
      operationId: contractScan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - contractAddress
              - chain
              properties:
                contractAddress:
                  type: string
                chain:
                  type: string
      responses:
        '200':
          description: Security scan results
          content:
            application/json:
              schema:
                type: object
                properties:
                  safetyScore:
                    type: number
                  vulnerabilities:
                    type: array
        '402':
          description: Payment Required
      x-featured: false
  /x402/instant-agent-wallet:
    post:
      tags:
      - Execution
      summary: Instant Agent Wallet
      description: Create a session-scoped ephemeral EVM wallet for AI agent operations. Returns address and encrypted key material with USDC funding instructions. Designed for single-session autonomous use.
      x-price-usd: 1
      operationId: instantAgentWallet
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                chain:
                  type: string
                  default: base
      responses:
        '200':
          description: Wallet created with address
        '402':
          description: Payment Required
      x-featured: true
  /x402/agent-create-wallet:
    post:
      tags:
      - Execution
      summary: Agent Wallet Provisioning (CDP)
      description: Create a persistent Coinbase Developer Platform (CDP) managed wallet for AI agents on Base mainnet. Returns wallet address and API credentials for long-running autonomous deployments.
      x-price-usd: 2
      operationId: agentCreateWallet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - agent_id
              properties:
                agent_id:
                  type: string
                  description: Unique agent identifier
                purpose:
                  type: string
                  enum:
                  - ephemeral
                  - persistent
                  default: persistent
                chain:
                  type: string
                  enum:
                  - base-mainnet
                  - ethereum-mainnet
                  - polygon-mainnet
                  - arbitrum-mainnet
                  default: base-mainnet
                labels:
                  type: array
                  items:
                    type: string
                tags:
                  type: array
                  items:
                    type: string
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: CDP wallet created
        '402':
          description: Payment Required
      x-featured: false
  /x402/seamless-chain-bridge:
    post:
      tags:
      - Execution
      summary: Seamless Chain Bridge
      description: Cross-chain bridge calldata via Across Protocol for Ethereum, Base, Arbitrum, Optimism, and Polygon. Returns unsigned bridge transaction with fee breakdown, estimated settlement time, and minimum received.
      x-price-usd: 2
      operationId: seamlessChainBridge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - fromChain
              - toChain
              - token
              - amount
              properties:
                fromChain:
                  type: string
                toChain:
                  type: string
                token:
                  type: string
                amount:
                  type: string
      responses:
        '200':
          description: Bridge transaction prepared
        '402':
          description: Payment Required
      x-featured: false
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