openapi: 3.2.0
info:
  title: 2s — the (most) everything Crypto API
  version: '1'
  summary: The (most) everything API.
  description: 'The (most) everything API for AI agents: 575+ pay-per-call endpoints on one origin.'
  contact:
    name: 2s
    url: https://2s.io
    email: alley@2s.io
  x-logo:
    url: https://2s.io/icon-512.png
    altText: 2s
  x-guidance: 'Pay-per-call REST API for AI agents — hundreds of endpoints returning ground-truth data (US public records, company & legal identifiers, finance/SEC, crypto/web3, security & CVEs, medical codes, weather & geocoding, agriculture, energy, maritime, music, and more). Every endpoint is paid per call in USDC via x402 (Base or Solana) — no API key, no signup. Call any endpoint with no auth to get a 402 PaymentRequirements envelope, sign it (EIP-3009 on Base, partial SPL transfer on Solana), and retry with the PAYMENT-SIGNATURE header. Add ?trial=1 for one free real call per endpoint per hour to test before paying. To discover the right endpoint: GET https://2s.io/api/directory for the full catalog, or GET https://2s.io/api/search/endpoints?q=<natural-language task> for a ranked match. Per-call price is on each operation as x-payment-info (from $0.001). Batch up to 50 calls behind one payment via POST https://2s.io/api/batch/run.'
servers:
- url: https://2s.io
tags:
- name: Crypto
paths:
  /api/crypto/address-history:
    get:
      tags:
      - Crypto
      summary: Transaction history for an Ethereum address (via Etherscan V2)
      description: 'Transaction history for an Ethereum address (via Etherscan V2). Returns normal transactions newest-first: hash, block, timestamp, from/to, value (wei + ETH), gas used, gas price, decoded method id + function name, error flag, and any contract created. Paginate with page + offset; bound with startBlock/endBlock. Defaults to Ethereum mainnet; other EVM chains are reachable by chainId where upstream coverage allows. Net-new vs crypto.tx (single-hash receipt).'
      operationId: crypto_address-history
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = transactions.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            hash:
                              nullable: true
                            blockNumber:
                              type: number
                              nullable: true
                            timestamp:
                              type: string
                              nullable: true
                            from:
                              nullable: true
                            to:
                              nullable: true
                            valueWei:
                              type: string
                              nullable: true
                            valueEth:
                              type: number
                              nullable: true
                            gasUsed:
                              type: number
                              nullable: true
                            gasPriceWei:
                              type: string
                              nullable: true
                            methodId:
                              nullable: true
                            functionName:
                              nullable: true
                            isError:
                              type: boolean
                            contractAddress:
                              type: string
                              nullable: true
                          required:
                          - blockNumber
                          - timestamp
                          - valueWei
                          - valueEth
                          - gasUsed
                          - gasPriceWei
                          - isError
                          - contractAddress
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.address-history
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: chainId
        in: query
        required: false
        description: EVM chain id; defaults to 1 (Ethereum). Other chains (8453 Base, 137 Polygon, 42161 Arbitrum…) require upstream multichain coverage.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: address
        in: query
        required: true
        description: Street address or full address string.
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: startBlock
        in: query
        required: false
        description: Start block.
        schema:
          type: integer
          minimum: 0
      - name: endBlock
        in: query
        required: false
        description: End block.
        schema:
          type: integer
          minimum: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/address-safety:
    get:
      tags:
      - Crypto
      summary: Malicious-wallet screen (via GoPlus, free/keyless)
      description: Malicious-wallet screen (via GoPlus, free/keyless). For any EVM address returns risk flags — cybercrime, money laundering, financial crime, darkweb, phishing, stealing/blackmail, fake KYC, mixer, sanctioned, honeypot-related, blacklist doubt and more — plus an overall malicious verdict and hit count. Counterparty risk check before interacting with an address.
      operationId: crypto_address-safety
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [address safety report].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chainId:
                              type: string
                            address:
                              type: string
                            malicious:
                              type: boolean
                            hitCount:
                              type: number
                            numberOfMaliciousContractsCreated:
                              type: number
                              nullable: true
                            dataSource:
                              nullable: true
                            flags:
                              type: object
                              additionalProperties:
                                type: boolean
                                nullable: true
                          required:
                          - chainId
                          - address
                          - malicious
                          - hitCount
                          - numberOfMaliciousContractsCreated
                          - flags
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.address-safety
      x-2s-version: null
      x-2s-price:
        usd: 0.004998
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004998'
        protocols:
        - x402: {}
      parameters:
      - name: chainId
        in: query
        required: true
        description: EVM chain id, e.g. 1, 56, 137, 8453.
        schema:
          type: string
          minLength: 1
          maxLength: 20
      - name: address
        in: query
        required: true
        description: Street address or full address string.
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/address-screen:
    get:
      tags:
      - Crypto
      summary: Sanctions-screen a crypto wallet address against the US
      description: Sanctions-screen a crypto wallet address against the US Treasury OFAC SDN list's published Digital Currency Addresses (BTC/ETH/USDT/XMR and more). Exact match — returns whether the address is sanctioned, and for any hit the listed entity name, OFAC programs, source id, and the currency the address was listed under. Compliance check before transacting. Distinct from crypto.address-safety (GoPlus behavioral risk) — this is regulatory sanctions.
      operationId: crypto_address-screen
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [screen result]; sanctioned=true means the address is OFAC-listed.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            address:
                              type: string
                            sanctioned:
                              type: boolean
                            matchCount:
                              type: number
                            matches:
                              type: array
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                  sourceList:
                                    type: string
                                  sourceId:
                                    type: string
                                    nullable: true
                                  entityType:
                                    type: string
                                    nullable: true
                                  programs:
                                    type: array
                                    items:
                                      type: string
                                  currencies:
                                    type: array
                                    items:
                                      type: string
                                required:
                                - name
                                - sourceList
                                - sourceId
                                - entityType
                                - programs
                                - currencies
                                additionalProperties: false
                          required:
                          - address
                          - sanctioned
                          - matchCount
                          - matches
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.address-screen
      x-2s-version: null
      x-2s-price:
        usd: 0.004998
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004998'
        protocols:
        - x402: {}
      parameters:
      - name: address
        in: query
        required: true
        description: Wallet address (any chain). Case-insensitive.
        schema:
          type: string
          minLength: 8
          maxLength: 120
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/address-validate:
    get:
      tags:
      - Crypto
      summary: Validate a cryptocurrency address with full checksum
      description: 'Validate a cryptocurrency address with full checksum verification (not just regex). Returns {chain, address, valid, canonical, format, reason}. Chains: btc (P2PKH, P2SH, Bech32 SegWit v0, Taproot Bech32m), eth (full EIP-55 checksum; non-checksummed flagged), sol (Ed25519 32-byte Base58), ltc (Base58Check L.../M.../3... + ltc1 Bech32), trx (T-prefix Base58Check 0x41), xrp (r-prefix custom Base58), bch (legacy Base58Check + bitcoincash:q... CashAddr). Catches typos via cryptographic checksum; canonical field returns the checksummed/lowercased form.'
      operationId: crypto_address-validate
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [validation result] (chain, address, valid, canonical, format, reason); total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chain:
                              type: string
                              enum:
                              - btc
                              - eth
                              - sol
                              - ltc
                              - trx
                              - xrp
                              - bch
                            address:
                              type: string
                              description: The address as submitted.
                            valid:
                              type: boolean
                            canonical:
                              type: string
                              nullable: true
                              description: Canonical checksummed/normalized form when valid.
                            format:
                              type: string
                              nullable: true
                              description: Sub-format when meaningful, e.g. 'p2pkh', 'eip-55', 'bech32-taproot', 'ed25519'.
                            reason:
                              type: string
                              nullable: true
                              description: Failure reason when valid=false.
                          required:
                          - chain
                          - address
                          - valid
                          - canonical
                          - format
                          - reason
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.address-validate
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: chain
        in: query
        required: true
        description: Chain.
        schema:
          type: string
          enum:
          - btc
          - eth
          - sol
          - ltc
          - trx
          - xrp
          - bch
      - name: address
        in: query
        required: true
        description: Street address or full address string.
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/balances:
    get:
      tags:
      - Crypto
      summary: Live native + ERC-20 token balances for an EVM address
      description: Live native + ERC-20 token balances for an EVM address (Base, Ethereum, Polygon, Arbitrum, Optimism; keyless). Returns the native-coin balance and, for any ERC-20 contract addresses you pass, the symbol, decimals, raw and human-formatted balance — fetched in one multicall. For wallet dashboards, treasury checks, and agent payment/settlement flows.
      operationId: crypto_balances
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [one balances object].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chain:
                              type: string
                            address:
                              type: string
                            native:
                              type: object
                              properties:
                                symbol:
                                  type: string
                                raw:
                                  type: string
                                balance:
                                  type: string
                              required:
                              - symbol
                              - raw
                              - balance
                              additionalProperties: false
                            tokens:
                              type: array
                              items:
                                type: object
                                properties:
                                  contract:
                                    type: string
                                  symbol:
                                    nullable: true
                                  decimals:
                                    type: number
                                  raw:
                                    type: string
                                    nullable: true
                                  balance:
                                    type: string
                                    nullable: true
                                required:
                                - contract
                                - decimals
                                - raw
                                - balance
                                additionalProperties: false
                          required:
                          - chain
                          - address
                          - native
                          - tokens
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.balances
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: address
        in: query
        required: true
        description: EVM address to read.
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - name: chain
        in: query
        required: false
        description: Default base.
        schema:
          type: string
          enum:
          - base
          - ethereum
          - polygon
          - arbitrum
          - optimism
      - name: tokens
        in: query
        required: false
        description: Comma-separated ERC-20 contract addresses (max 20).
        schema:
          type: string
          maxLength: 900
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/btc-address:
    get:
      tags:
      - Crypto
      summary: 'Bitcoin address summary (free/keyless): confirmed balance'
      description: 'Bitcoin address summary (free/keyless): confirmed balance (sats + BTC), total received/sent, transaction count, funded/spent output counts, and pending mempool balance + tx count. Works for any BTC address (legacy, SegWit, Taproot). Net-new — our on-chain reads were EVM-only.'
      operationId: crypto_btc-address
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [address summary].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            address:
                              type: string
                            balanceSats:
                              type: number
                            balanceBtc:
                              type: number
                            totalReceivedBtc:
                              type: number
                            totalSentBtc:
                              type: number
                            txCount:
                              type: number
                              nullable: true
                            fundedTxoCount:
                              type: number
                              nullable: true
                            spentTxoCount:
                              type: number
                              nullable: true
                            mempoolBalanceSats:
                              type: number
                            mempoolTxCount:
                              type: number
                              nullable: true
                          required:
                          - address
                          - balanceSats
                          - balanceBtc
                          - totalReceivedBtc
                          - totalSentBtc
                          - txCount
                          - fundedTxoCount
                          - spentTxoCount
                          - mempoolBalanceSats
                          - mempoolTxCount
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.btc-address
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: address
        in: query
        required: true
        description: Bitcoin address (1.../3.../bc1...).
        schema:
          type: string
          minLength: 20
          maxLength: 100
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/btc-fees:
    get:
      tags:
      - Crypto
      summary: Current Bitcoin network fee rates and mempool backlog from
      description: Current Bitcoin network fee rates and mempool backlog from mempool.space. Returns recommended fee rates in satoshis per virtual byte for target confirmation speeds (fastest ~next block, half-hour, hour, economy, minimum) plus the current mempool size (transaction count, total vsize, total fees waiting). Keyless, live. The BTC counterpart to crypto.gas-oracle (Ethereum) — fresh, fast-moving network state an agent cannot recall, for wallets, payment timing, and fee estimation.
      operationId: crypto_btc-fees
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [one fee/mempool snapshot]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            recommendedFeesSatPerVByte:
                              type: object
                              properties:
                                fastest:
                                  type: number
                                  nullable: true
                                halfHour:
                                  type: number
                                  nullable: true
                                hour:
                                  type: number
                                  nullable: true
                                economy:
                                  type: number
                                  nullable: true
                                minimum:
                                  type: number
                                  nullable: true
                              required:
                              - fastest
                              - halfHour
                              - hour
                              - economy
                              - minimum
                              additionalProperties: false
                            mempool:
                              type: object
                              properties:
                                txCount:
                                  type: number
                                  nullable: true
                                vsizeBytes:
                                  type: number
                                  nullable: true
                                totalFeeSat:
                                  type: number
                                  nullable: true
                              required:
                              - txCount
                              - vsizeBytes
                              - totalFeeSat
                              additionalProperties: false
                            source:
                              $ref: '#/components/schemas/Source'
                            note:
                              type: string
                          required:
                          - recommendedFeesSatPerVByte
                          - mempool
                          - source
                          - note
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.btc-fees
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/btc-mempool:
    get:
      tags:
      - Crypto
      summary: 'Bitcoin mempool state (free/keyless): current unconfirmed'
      description: 'Bitcoin mempool state (free/keyless): current unconfirmed tx count, total vsize, and total fees, plus the most recent transactions (whale radar) — filter with minBtc to surface only large pending transfers. For congestion monitoring and large-transfer alerts.'
      operationId: crypto_btc-mempool
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [{ summary, recent }].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            summary:
                              type: object
                              properties:
                                txCount:
                                  type: number
                                  nullable: true
                                vsize:
                                  type: number
                                  nullable: true
                                totalFeeSats:
                                  type: number
                              required:
                              - txCount
                              - vsize
                              - totalFeeSats
                              additionalProperties: false
                            recent:
                              type: array
                              items:
                                type: object
                                properties:
                                  txid:
                                    nullable: true
                                  valueBtc:
                                    type: number
                                  valueSats:
                                    type: number
                                  feeSats:
                                    type: number
                                  vsize:
                                    type: number
                                    nullable: true
                                required:
                                - valueBtc
                                - valueSats
                                - feeSats
                                - vsize
                                additionalProperties: false
                          required:
                          - summary
                          - recent
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.btc-mempool
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: minBtc
        in: query
        required: false
        description: Only include recent txs >= this BTC value.
        schema:
          type: number
          minimum: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/btc-tx:
    get:
      tags:
      - Crypto
      summary: Bitcoin transaction lookup by txid (free/keyless)
      description: 'Bitcoin transaction lookup by txid (free/keyless): confirmed status + confirmation count (vs current tip), block height + time, fee (sats + BTC), total output value, size/weight, and input/output counts. Distinct from crypto.tx (EVM) — this is Bitcoin.'
      operationId: crypto_btc-tx
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [transaction].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            txid:
                              nullable: true
                            confirmed:
                              type: boolean
                            confirmations:
                              type: number
                            blockHeight:
                              type: number
                              nullable: true
                            blockTime:
                              type: string
                              nullable: true
                            feeSats:
                              type: number
                            feeBtc:
                              type: number
                            valueOutSats:
                              type: number
                            valueOutBtc:
                              type: number
                            sizeBytes:
                              type: number
                              nullable: true
                            weight:
                              type: number
                              nullable: true
                            vinCount:
                              type: number
                              nullable: true
                            voutCount:
                              type: number
                              nullable: true
                          required:
                          - confirmed
                          - confirmations
                          - blockHeight
                          - blockTime
                          - feeSats
                          - feeBtc
                          - valueOutSats
                          - valueOutBtc
                          - sizeBytes
                          - weight
                          - vinCount
                          - voutCount
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.btc-tx
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: txid
        in: query
        required: true
        description: Txid.
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{64}$
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/btc-utxos:
    get:
      tags:
      - Crypto
      summary: Unspent transaction outputs (UTXOs) for a Bitcoin address
      description: 'Unspent transaction outputs (UTXOs) for a Bitcoin address (free/keyless): each with txid, output index, value (sats + BTC), confirmation status, and block height. Sorted largest-first. For coin selection, balance verification, and wallet tooling.'
      operationId: crypto_btc-utxos
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = UTXOs (largest first).'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            txid:
                              nullable: true
                            vout:
                              type: number
                              nullable: true
                            valueSats:
                              type: number
                            valueBtc:
                              type: number
                            confirmed:
                              type: boolean
                              nullable: true
                            blockHeight:
                              type: number
                              nullable: true
                          required:
                          - vout
                          - valueSats
                          - valueBtc
                          - confirmed
                          - blockHeight
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.btc-utxos
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: address
        in: query
        required: true
        description: Street address or full address string.
        schema:
          type: string
          minLength: 20
          maxLength: 100
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 500
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/cex-klines:
    get:
      tags:
      - Crypto
      summary: Centralized-exchange OHLCV candlesticks for a spot trading
      description: 'Centralized-exchange OHLCV candlesticks for a spot trading pair (e.g. BTC-USD, ETH-USD, SOL-USD), free/keyless. Pass interval (1m/5m/15m/1h/6h/1d) and limit. Each bar: time, open, high, low, close, volume. Net-new vs crypto.dex-ohlcv (on-chain DEX) — this is CEX spot.'
      operationId: crypto_cex-klines
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = OHLCV bars (newest first).'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            time:
                              type: string
                              nullable: true
                            open:
                              type: number
                              nullable: true
                            high:
                              type: number
                              nullable: true
                            low:
                              type: number
                              nullable: true
                            close:
                              type: number
                              nullable: true
                            volume:
                              type: number
                              nullable: true
                          required:
                          - time
                          - open
                          - high
                          - low
                          - close
                          - volume
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.cex-klines
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: pair
        in: query
        required: true
        description: Trading pair, e.g. BTC-USD.
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{2,10}-[A-Za-z0-9]{2,10}$
      - name: interval
        in: query
        required: false
        description: Interval.
        schema:
          type: string
          enum:
          - 1m
          - 5m
          - 15m
          - 1h
          - 6h
          - 1d
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 300
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/cex-ticker:
    get:
      tags:
      - Crypto
      summary: Centralized-exchange 24h ticker for a spot pair (e.g
      description: 'Centralized-exchange 24h ticker for a spot pair (e.g. BTC-USD), free/keyless: current price, best bid/ask, 24h open/high/low, 24h + 30d volume, and 24h percent change. Real CEX spot quote — distinct from crypto.token-price (CoinGecko aggregate).'
      operationId: crypto_cex-ticker
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [ticker].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            pair:
                              type: string
                            price:
                              type: number
                              nullable: true
                            bid:
                              type: number
                              nullable: true
                            ask:
                              type: number
                              nullable: true
                            open24h:
                              type: number
                              nullable: true
                            high24h:
                              type: number
                              nullable: true
                            low24h:
                              type: number
                              nullable: true
                            volume24h:
                              type: number
                              nullable: true
                            volume30d:
                              type: number
                              nullable: true
                            change24hPct:
                              type: number
                              nullable: true
                            time:
                              nullable: true
                          required:
                          - pair
                          - price
                          - bid
                          - ask
                          - open24h
                          - high24h
                          - low24h
                          - volume24h
                          - volume30d
                          - change24hPct
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.cex-ticker
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: pair
        in: query
        required: true
        description: Pair.
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{2,10}-[A-Za-z0-9]{2,10}$
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/chain-tvl-history:
    get:
      tags:
      - Crypto
      summary: Historical total DeFi TVL time series for a blockchain (e.g
      description: Historical total DeFi TVL time series for a blockchain (e.g. Ethereum, Solana, Arbitrum), via DefiLlama (free/keyless). Returns daily { date, tvlUsd } points (most recent N, default 90). For charting a chain's DeFi capital over time. Pair with crypto.defi-chains for the current cross-chain leaderboard.
      operationId: crypto_chain-tvl-history
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [{ chain, series }].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chain:
                              type: string
                            series:
                              type: array
                              items:
                                type: object
                                properties:
                                  date:
                                    type: number
                                    nullable: true
                                  tvlUsd:
                                    type: number
                                    nullable: true
                                required:
                                - date
                                - tvlUsd
                                additionalProperties: false
                          required:
                          - chain
                          - series
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.chain-tvl-history
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: chain
        in: query
        required: true
        description: Chain name, e.g. Ethereum, Solana, Arbitrum, Base.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: limit
        in: query
        required: false
        description: Most-recent N daily points (default 90).
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/coin:
    get:
      tags:
      - Crypto
      summary: Full coin profile by CoinGecko id (e.g
      description: Full coin profile by CoinGecko id (e.g. bitcoin, ethereum, solana). Returns price, market cap + rank, FDV, 24h volume, all-time high/low with dates, circulating/total/max supply, price changes (1h/24h/7d/30d/1y), categories, and official links (homepage, X, GitHub, subreddit). Richer than crypto.token-price (spot only) and crypto.markets (list row).
      operationId: crypto_coin
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [coin profile].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              nullable: true
                            symbol:
                              type: string
                            name:
                              type: string
                              nullable: true
                            marketCapRank:
                              type: number
                              nullable: true
                            categories:
                              type: array
                              items:
                                type: string
                            priceUsd:
                              type: number
                              nullable: true
                            marketCapUsd:
                              type: number
                              nullable: true
                            fdvUsd:
                              type: number
                              nullable: true
                            volume24hUsd:
                              type: number
                              nullable: true
                            athUsd:
                              type: number
                              nullable: true
                            athDate:
                              nullable: true
                            atlUsd:
                              type: number
                              nullable: true
                            atlDate:
                              nullable: true
                            circulatingSupply:
                              type: number
                              nullable: true
                            totalSupply:
                              type: number
                              nullable: true
                            maxSupply:
                              type: number
                              nullable: true
                            change1hPct:
                              type: number
                              nullable: true
                            change24hPct:
                              type: number
                              nullable: true
                            change7dPct:
                              type: number
                              nullable: true
                            change30dPct:
                              type: number
                              nullable: true
                            change1yPct:
                              type: number
                              nullable: true
                            homepage:
                              type: string
                              nullable: true
                            twitter:
                              type: string
                              nullable: true
                            github:
                              type: string
                              nullable: true
                            subreddit:
                              type: string
                              nullable: true
                          required:
                          - id
                          - symbol
                          - name
                          - marketCapRank
                          - categories
                          - priceUsd
                          - marketCapUsd
                          - fdvUsd
                          - volume24hUsd
                          - athUsd
                          - atlUsd
                          - circulatingSupply
                          - totalSupply
                          - maxSupply
                          - change1hPct
                          - change24hPct
                          - change7dPct
                          - change30dPct
                          - change1yPct
                          - homepage
                          - twitter
                          - github
                          - subreddit
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.coin
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: query
        required: true
        description: CoinGecko coin id, e.g. bitcoin, ethereum, solana.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/coin-history:
    get:
      tags:
      - Crypto
      summary: Historical market chart for a coin by CoinGecko id
      description: 'Historical market chart for a coin by CoinGecko id: time-series of price, market cap, and volume over the last N days (1-365) in USD or another vs-currency. Granularity is auto-selected by range (hourly for short windows, daily for long). For backtests, charts, and trend analysis.'
      operationId: crypto_coin-history
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [{ prices, marketCaps, volumes }].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            prices:
                              type: array
                              items:
                                type: object
                                properties:
                                  time:
                                    type: number
                                  value:
                                    type: number
                                    nullable: true
                                required:
                                - time
                                - value
                                additionalProperties: false
                            marketCaps:
                              type: array
                              items:
                                type: object
                                properties:
                                  time:
                                    type: number
                                  value:
                                    type: number
                                    nullable: true
                                required:
                                - time
                                - value
                                additionalProperties: false
                            volumes:
                              type: array
                              items:
                                type: object
                                properties:
                                  time:
                                    type: number
                                  value:
                                    type: number
                                    nullable: true
                                required:
                                - time
                                - value
                                additionalProperties: false
                          required:
                          - prices
                          - marketCaps
                          - volumes
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.coin-history
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: id
        in: query
        required: true
        description: CoinGecko coin id, e.g. bitcoin.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: days
        in: query
        required: false
        description: Lookback in days (default 7).
        schema:
          type: integer
          minimum: 1
          maximum: 365
      - name: vs
        in: query
        required: false
        description: vs-currency (default usd).
        schema:
          type: string
          maxLength: 10
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/contract:
    get:
      tags:
      - Crypto
      summary: Decode an EVM smart contract
      description: 'Decode an EVM smart contract. Pass chain (ethereum, base, polygon, arbitrum, optimism, bsc, avalanche) + address; returns whether the contract is source-verified (Sourcify), its name/compiler/language, whether it is a proxy and its implementation address, and human-readable function and event signatures from the ABI. Optionally pass selector (a 0x 4-byte function selector) to decode what it calls — resolved from the contract''s own ABI when verified, otherwise from the public 4byte directory. Pairs with crypto.tx (which gives a `to` address + calldata): turn an opaque contract + selector into "what is this and what does it do." Free, keyless.'
      operationId: crypto_contract
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items[0] = the contract (verification, ABI signatures, proxy, optional decoded selector).'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chain:
                              type: string
                            address:
                              type: string
                            verified:
                              type: boolean
                              description: Source-verified on Sourcify.
                            name:
                              type: string
                              nullable: true
                            compiler:
                              type: string
                              nullable: true
                            language:
                              type: string
                              nullable: true
                            isProxy:
                              type: boolean
                            implementation:
                              type: string
                              nullable: true
                              description: Implementation address if a proxy.
                            functionCount:
                              type: integer
                            functions:
                              type: array
                              items:
                                type: string
                              description: Function signatures from the ABI.
                            events:
                              type: array
                              items:
                                type: string
                              description: Event signatures from the ABI.
                            decoded:
                              type: object
                              properties:
                                selector:
                                  type: string
                                signature:
                                  type: string
                                  nullable: true
                                source:
                                  type: string
                              required:
                              - selector
                              - signature
                              - source
                              additionalProperties: false
                              description: Decoded selector (when selector passed).
                          required:
                          - chain
                          - address
                          - verified
                          - name
                          - compiler
                          - language
                          - isProxy
                          - implementation
                          - functionCount
                          - functions
                          - events
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          verified:
                            type: boolean
                        required:
                        - verified
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.contract
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: chain
        in: query
        required: true
        description: 'EVM chain: ethereum, base, polygon, arbitrum, optimism, bsc, or avalanche.'
        schema:
          type: string
          enum:
          - ethereum
          - base
          - polygon
          - arbitrum
          - optimism
          - bsc
          - avalanche
      - name: address
        in: query
        required: true
        description: 0x-prefixed 40-hex contract address.
        schema:
          type: string
      - name: selector
        in: query
        required: false
        description: Optional 0x 4-byte function selector to decode (e.g. 0xa9059cbb).
        schema:
          type: string
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/decode-calldata:
    post:
      tags:
      - Crypto
      summary: Decode raw EVM transaction calldata
      description: Decode raw EVM transaction calldata. POST { data } (0x-prefixed hex). Resolves the 4-byte function selector to its human signature(s) via the openchain.xyz database, then ABI-decodes the parameters (address, uint/int, bool, bytesN, string, bytes, and elementary dynamic arrays). Returns selector, candidate signatures, decoded params, and the raw 32-byte words. For agents inspecting/verifying a transaction before signing. Keyless.
      operationId: crypto_decode-calldata
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [decoded calldata].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            selector:
                              type: string
                            signatures:
                              type: array
                              items:
                                type: string
                            decoded:
                              type: object
                              properties:
                                signature:
                                  type: string
                                params:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      type:
                                        type: string
                                      value: {}
                                    required:
                                    - type
                                    additionalProperties: false
                              required:
                              - signature
                              - params
                              additionalProperties: false
                              nullable: true
                            rawWords:
                              type: array
                              items:
                                type: string
                            note:
                              type: string
                              nullable: true
                          required:
                          - selector
                          - signatures
                          - decoded
                          - rawWords
                          - note
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.decode-calldata
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: string
                  pattern: ^0x?[0-9a-fA-F]{8,}$
                  maxLength: 60000
                  description: Data.
              required:
              - data
              additionalProperties: false
      parameters:
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/defi:
    get:
      tags:
      - Crypto
      summary: DeFi total-value-locked (TVL) metrics via DefiLlama
      description: DeFi total-value-locked (TVL) metrics via DefiLlama. With no params, returns the top protocols by TVL (name, slug, category, TVL, 1-day and 7-day % change, chains) plus total DeFi TVL across all chains. Pass protocol= (e.g. lido, aave, uniswap) for a single protocol's TVL, category, momentum, and chains; or chain= (e.g. ethereum, solana, arbitrum) for that chain's TVL. Distinct from crypto.markets/token-price (spot prices) — this is protocol- and chain-level capital locked in DeFi, which an agent can't know from training. Free, keyless.
      operationId: crypto_defi
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = protocol(s) or a chain; meta.mode = protocol|chain|top, meta.totalTvl = total DeFi TVL.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              nullable: true
                            slug:
                              type: string
                              nullable: true
                              description: DefiLlama protocol slug.
                            category:
                              type: string
                              nullable: true
                              description: Protocol category (e.g. Liquid Staking, Lending).
                            tvl:
                              type: number
                              nullable: true
                              description: Total value locked, USD.
                            change1d:
                              type: number
                              nullable: true
                              description: 1-day TVL change, %.
                            change7d:
                              type: number
                              nullable: true
                              description: 7-day TVL change, %.
                            chains:
                              type: array
                              items:
                                type: string
                              nullable: true
                              description: Chains the protocol is deployed on.
                            tokenSymbol:
                              type: string
                              nullable: true
                              description: Native token symbol (chain mode).
                          required:
                          - name
                          - slug
                          - category
                          - tvl
                          - change1d
                          - change7d
                          - chains
                          - tokenSymbol
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          mode:
                            type: string
                          totalTvl:
                            type: number
                            nullable: true
                        required:
                        - mode
                        - totalTvl
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.defi
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: protocol
        in: query
        required: false
        description: Protocol slug (e.g. lido, aave, uniswap). Omit for the top-protocols list.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: chain
        in: query
        required: false
        description: Chain name (e.g. ethereum, solana, arbitrum) for that chain's TVL.
        schema:
          type: string
          minLength: 1
          maxLength: 60
      - name: limit
        in: query
        required: false
        description: Number of protocols in the top list (1–100, default 20).
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/defi-chains:
    get:
      tags:
      - Crypto
      summary: DeFi TVL leaderboard across all chains (via DefiLlama
      description: 'DeFi TVL leaderboard across all chains (via DefiLlama, free/keyless): every chain ranked by total value locked, with its native token symbol and chain id. Distinct from crypto.defi (which returns one chain''s TVL by name) — this is the full ranked cross-chain comparison.'
      operationId: crypto_defi-chains
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = chains by TVL desc.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              nullable: true
                            tvlUsd:
                              type: number
                              nullable: true
                            tokenSymbol:
                              nullable: true
                            chainId:
                              nullable: true
                          required:
                          - tvlUsd
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.defi-chains
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/defi-fees:
    get:
      tags:
      - Crypto
      summary: Protocol fees/revenue or DEX trading volume leaderboards
      description: Protocol fees/revenue or DEX trading volume leaderboards (via DefiLlama, free/keyless). kind=fees ranks protocols by fees generated; kind=dexs ranks DEXes by trading volume. Each row has 24h/7d/30d/1y totals + 1-month change, plus catalog totals. Sort by total24h/7d/30d. The protocol-economics layer.
      operationId: crypto_defi-fees
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = protocols ranked; meta = catalog totals.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              nullable: true
                            category:
                              nullable: true
                            total24h:
                              type: number
                              nullable: true
                            total7d:
                              type: number
                              nullable: true
                            total30d:
                              type: number
                              nullable: true
                            total1y:
                              type: number
                              nullable: true
                            change1m:
                              type: number
                              nullable: true
                          required:
                          - total24h
                          - total7d
                          - total30d
                          - total1y
                          - change1m
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          total24h:
                            type: number
                            nullable: true
                          total7d:
                            type: number
                            nullable: true
                          total30d:
                            type: number
                            nullable: true
                        required:
                        - total24h
                        - total7d
                        - total30d
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.defi-fees
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: kind
        in: query
        required: false
        description: Kind.
        schema:
          type: string
          enum:
          - fees
          - dexs
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          enum:
          - total24h
          - total7d
          - total30d
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/defi-protocol-history:
    get:
      tags:
      - Crypto
      summary: Historical total-value-locked (TVL) time series for a DeFi
      description: Historical total-value-locked (TVL) time series for a DeFi protocol by slug (e.g. aave, lido, uniswap), via DefiLlama (free/keyless). Returns daily { date, tvlUsd } points (most recent N, default 90) plus the protocol's chains. For charting a protocol's growth or decline over time. Net-new vs crypto.defi (current TVL only).
      operationId: crypto_defi-protocol-history
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [{ name, chains, series }].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                            chains:
                              type: array
                              items:
                                type: string
                            series:
                              type: array
                              items:
                                type: object
                                properties:
                                  date:
                                    type: number
                                    nullable: true
                                  tvlUsd:
                                    type: number
                                    nullable: true
                                required:
                                - date
                                - tvlUsd
                                additionalProperties: false
                          required:
                          - name
                          - chains
                          - series
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.defi-protocol-history
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: slug
        in: query
        required: true
        description: DefiLlama protocol slug, e.g. aave, lido, uniswap.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: limit
        in: query
        required: false
        description: Most-recent N daily points (default 90).
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/defi-yields:
    get:
      tags:
      - Crypto
      summary: DeFi yield & lending rates across protocols (via DefiLlama
      description: DeFi yield & lending rates across protocols (via DefiLlama, free/keyless). Returns pools ranked by APY or TVL with base vs reward APY, TVL, 1d/7d/30d APY trend, stablecoin flag, and IL-risk. Filter by chain, project (aave, compound, lido…), symbol (USDC, ETH…), minApy, minTvlUsd. The yield/lending-rate layer beyond crypto.defi's TVL headline.
      operationId: crypto_defi-yields
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = yield pools.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            project:
                              nullable: true
                            symbol:
                              nullable: true
                            chain:
                              nullable: true
                            tvlUsd:
                              type: number
                              nullable: true
                            apy:
                              type: number
                              nullable: true
                            apyBase:
                              type: number
                              nullable: true
                            apyReward:
                              type: number
                              nullable: true
                            apyPct1D:
                              type: number
                              nullable: true
                            apyPct7D:
                              type: number
                              nullable: true
                            apyPct30D:
                              type: number
                              nullable: true
                            stablecoin:
                              type: boolean
                              nullable: true
                            ilRisk:
                              nullable: true
                            pool:
                              nullable: true
                          required:
                          - tvlUsd
                          - apy
                          - apyBase
                          - apyReward
                          - apyPct1D
                          - apyPct7D
                          - apyPct30D
                          - stablecoin
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.defi-yields
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: chain
        in: query
        required: false
        description: Chain.
        schema:
          type: string
          maxLength: 40
      - name: project
        in: query
        required: false
        description: Project.
        schema:
          type: string
          maxLength: 60
      - name: symbol
        in: query
        required: false
        description: Symbol.
        schema:
          type: string
          maxLength: 40
      - name: minApy
        in: query
        required: false
        description: Min apy.
        schema:
          type: number
          minimum: 0
      - name: minTvlUsd
        in: query
        required: false
        description: Min tvl usd.
        schema:
          type: number
          minimum: 0
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          enum:
          - apy
          - tvl
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/dex-networks:
    get:
      tags:
      - Crypto
      summary: List the 100+ blockchain networks supported by the on-chain
      description: List the 100+ blockchain networks supported by the on-chain DEX endpoints (via GeckoTerminal, free/keyless). Each entry has the network slug to use with crypto.dex-pools / dex-ohlcv / dex-search / token-info, its display name, and CoinGecko asset-platform id. Call this to discover valid network slugs.
      operationId: crypto_dex-networks
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = supported networks.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              nullable: true
                            name:
                              nullable: true
                            coingeckoAssetPlatformId:
                              nullable: true
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.dex-networks
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/dex-ohlcv:
    get:
      tags:
      - Crypto
      summary: OHLCV candlesticks for a DEX pool (via GeckoTerminal
      description: OHLCV candlesticks for a DEX pool (via GeckoTerminal, free/keyless). Pass network + pool address + timeframe (day/hour/minute) with optional aggregate (e.g. 4 = 4-hour) and limit. Returns time/open/high/low/close/volumeUsd bars for on-chain technical analysis. Pair with crypto.dex-pools / dex-token-pools to find a pool address.
      operationId: crypto_dex-ohlcv
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = OHLCV bars (newest first).'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            time:
                              type: number
                              nullable: true
                            open:
                              type: number
                              nullable: true
                            high:
                              type: number
                              nullable: true
                            low:
                              type: number
                              nullable: true
                            close:
                              type: number
                              nullable: true
                            volumeUsd:
                              type: number
                              nullable: true
                          required:
                          - time
                          - open
                          - high
                          - low
                          - close
                          - volumeUsd
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.dex-ohlcv
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: network
        in: query
        required: true
        description: Network.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: address
        in: query
        required: true
        description: Pool address (not token address).
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: timeframe
        in: query
        required: false
        description: Timeframe.
        schema:
          type: string
          enum:
          - day
          - hour
          - minute
      - name: aggregate
        in: query
        required: false
        description: Aggregate.
        schema:
          type: integer
          minimum: 1
          maximum: 60
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/dex-pools:
    get:
      tags:
      - Crypto
      summary: Trending or newly-created DEX liquidity pools on a network
      description: 'Trending or newly-created DEX liquidity pools on a network (via GeckoTerminal, free/keyless). kind=trending (hot pools) or kind=new (freshly launched — early-token discovery). Each pool: pair name, base/quote USD price, FDV, market cap, reserve, 24h volume, 24h price change, and 24h buys/sells. Networks: eth, bsc, polygon_pos, base, arbitrum, solana, and 100+ more.'
      operationId: crypto_dex-pools
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = DEX pools.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            address:
                              nullable: true
                            name:
                              nullable: true
                            baseTokenPriceUsd:
                              type: number
                              nullable: true
                            quoteTokenPriceUsd:
                              type: number
                              nullable: true
                            fdvUsd:
                              type: number
                              nullable: true
                            marketCapUsd:
                              type: number
                              nullable: true
                            reserveUsd:
                              type: number
                              nullable: true
                            volume24hUsd:
                              type: number
                              nullable: true
                            priceChange24hPct:
                              type: number
                              nullable: true
                            buys24h:
                              type: number
                              nullable: true
                            sells24h:
                              type: number
                              nullable: true
                            poolCreatedAt:
                              nullable: true
                          required:
                          - baseTokenPriceUsd
                          - quoteTokenPriceUsd
                          - fdvUsd
                          - marketCapUsd
                          - reserveUsd
                          - volume24hUsd
                          - priceChange24hPct
                          - buys24h
                          - sells24h
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.dex-pools
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: network
        in: query
        required: true
        description: GeckoTerminal network slug, e.g. eth, bsc, base, solana.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: kind
        in: query
        required: false
        description: Kind.
        schema:
          type: string
          enum:
          - trending
          - new
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/dex-search:
    get:
      tags:
      - Crypto
      summary: Search on-chain DEX liquidity pools by token name, symbol
      description: Search on-chain DEX liquidity pools by token name, symbol, or address (via GeckoTerminal, free/keyless). Optionally scope to one network. Returns matching pools with pair name, USD price, FDV, market cap, reserve, 24h volume + price change, and buys/sells — the fast way to find the right pool/token before pulling OHLCV or token info.
      operationId: crypto_dex-search
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = matching pools.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            address:
                              nullable: true
                            name:
                              nullable: true
                            baseTokenPriceUsd:
                              type: number
                              nullable: true
                            quoteTokenPriceUsd:
                              type: number
                              nullable: true
                            fdvUsd:
                              type: number
                              nullable: true
                            marketCapUsd:
                              type: number
                              nullable: true
                            reserveUsd:
                              type: number
                              nullable: true
                            volume24hUsd:
                              type: number
                              nullable: true
                            priceChange24hPct:
                              type: number
                              nullable: true
                            buys24h:
                              type: number
                              nullable: true
                            sells24h:
                              type: number
                              nullable: true
                            poolCreatedAt:
                              nullable: true
                          required:
                          - baseTokenPriceUsd
                          - quoteTokenPriceUsd
                          - fdvUsd
                          - marketCapUsd
                          - reserveUsd
                          - volume24hUsd
                          - priceChange24hPct
                          - buys24h
                          - sells24h
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.dex-search
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: query
        in: query
        required: true
        description: Token name, symbol, or contract address.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: network
        in: query
        required: false
        description: Optional network slug to scope the search.
        schema:
          type: string
          maxLength: 40
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/dex-token-pools:
    get:
      tags:
      - Crypto
      summary: All DEX pools trading a given token, by contract address
      description: All DEX pools trading a given token, by contract address (via GeckoTerminal, free/keyless). Returns each pool's pair, on-chain USD price, FDV/market cap, liquidity reserve, 24h volume + price change, and buys/sells — the on-chain price + liquidity picture for any token across a network's DEXes.
      operationId: crypto_dex-token-pools
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = pools trading the token.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            address:
                              nullable: true
                            name:
                              nullable: true
                            baseTokenPriceUsd:
                              type: number
                              nullable: true
                            quoteTokenPriceUsd:
                              type: number
                              nullable: true
                            fdvUsd:
                              type: number
                              nullable: true
                            marketCapUsd:
                              type: number
                              nullable: true
                            reserveUsd:
                              type: number
                              nullable: true
                            volume24hUsd:
                              type: number
                              nullable: true
                            priceChange24hPct:
                              type: number
                              nullable: true
                            buys24h:
                              type: number
                              nullable: true
                            sells24h:
                              type: number
                              nullable: true
                            poolCreatedAt:
                              nullable: true
                          required:
                          - baseTokenPriceUsd
                          - quoteTokenPriceUsd
                          - fdvUsd
                          - marketCapUsd
                          - reserveUsd
                          - volume24hUsd
                          - priceChange24hPct
                          - buys24h
                          - sells24h
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.dex-token-pools
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: network
        in: query
        required: true
        description: Network slug, e.g. eth, bsc, base, solana.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: address
        in: query
        required: true
        description: Token contract address.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/ens-resolve:
    get:
      tags:
      - Crypto
      summary: Resolve ENS (Ethereum Name Service) names and addresses
      description: 'Resolve ENS (Ethereum Name Service) names and addresses live on Ethereum mainnet. Pass query as either an ENS name (e.g. "vitalik.eth") → returns the Ethereum address it points to, or a 0x address → returns its primary ENS name (reverse record). Either way it also returns the profile text records: avatar, email, url, twitter (com.twitter), github (com.github), and description. A live on-chain lookup agents can''t do from their sandbox, and ENS records change after training cutoffs. Wallet UX, address-book resolution, on-chain identity. Returns address:null for an unregistered or unset name.'
      operationId: crypto_ens-resolve
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [ENS resolution] (query, name, address, profile records); total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            query:
                              type: string
                            name:
                              type: string
                              nullable: true
                            address:
                              type: string
                              nullable: true
                            records:
                              type: object
                              properties:
                                avatar:
                                  type: string
                                  nullable: true
                                email:
                                  type: string
                                  nullable: true
                                url:
                                  type: string
                                  nullable: true
                                twitter:
                                  type: string
                                  nullable: true
                                github:
                                  type: string
                                  nullable: true
                                description:
                                  type: string
                                  nullable: true
                              required:
                              - avatar
                              - email
                              - url
                              - twitter
                              - github
                              - description
                              additionalProperties: false
                          required:
                          - query
                          - name
                          - address
                          - records
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.ens-resolve
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: query
        in: query
        required: true
        description: Free-text search query.
        schema:
          type: string
          minLength: 3
          maxLength: 255
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/fear-greed:
    get:
      tags:
      - Crypto
      summary: The Crypto Fear & Greed Index - a 0-100 market-sentiment
      description: 'The Crypto Fear & Greed Index — a 0–100 market-sentiment gauge (0 = Extreme Fear, 100 = Extreme Greed) updated daily. Returns the current value + its classification (Extreme Fear/Fear/Neutral/Greed/Extreme Greed) and timestamp; pass limit (up to 90) for recent history. Useful as a contrarian sentiment signal. Source: alternative.me.'
      operationId: crypto_fear-greed
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = readings (newest first); total = count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            value:
                              type: number
                              description: 0–100 (0 = extreme fear, 100 = extreme greed).
                            classification:
                              type: string
                            timestamp:
                              type: string
                          required:
                          - value
                          - classification
                          - timestamp
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.fear-greed
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 90
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/gas-oracle:
    get:
      tags:
      - Crypto
      summary: Live EVM gas oracle. Returns latest block baseFeePerGas +
      description: 'Live EVM gas oracle. Returns latest block baseFeePerGas + slow/standard/fast tiers derived from priority-fee percentiles (p25/p50/p75) over the trailing 4 blocks, plus a 21,000-gas transfer cost estimate in the chain native unit. Chains: base, ethereum, polygon, arbitrum, optimism. Real-time post-training data, ~5s freshness.'
      operationId: crypto_gas-oracle
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [gas oracle] (latest block baseFee, slow/standard/fast priority tiers, 21k transfer estimate); total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chain:
                              type: object
                              properties:
                                key:
                                  type: string
                                name:
                                  type: string
                                chainId:
                                  type: number
                                nativeSymbol:
                                  type: string
                              required:
                              - key
                              - name
                              - chainId
                              - nativeSymbol
                              additionalProperties: false
                            block:
                              type: object
                              properties:
                                number:
                                  type: number
                                baseFeePerGasWei:
                                  type: string
                                  description: EIP-1559 base fee of the latest block, wei (decimal string).
                                baseFeePerGasGwei:
                                  type: number
                                timestamp:
                                  type: number
                                  description: Block time, Unix ms.
                              required:
                              - number
                              - baseFeePerGasWei
                              - baseFeePerGasGwei
                              - timestamp
                              additionalProperties: false
                            tiers:
                              type: object
                              properties:
                                slow:
                                  type: object
                                  properties:
                                    priorityFeePerGasGwei:
                                      type: number
                                    maxFeePerGasGwei:
                                      type: number
                                      description: baseFee + priority, gwei.
                                    priorityFeePerGasWei:
                                      type: string
                                    maxFeePerGasWei:
                                      type: string
                                    transferNativeCost:
                                      type: number
                                      description: Estimated 21,000-gas transfer cost in the chain native unit.
                                  required:
                                  - priorityFeePerGasGwei
                                  - maxFeePerGasGwei
                                  - priorityFeePerGasWei
                                  - maxFeePerGasWei
                                  - transferNativeCost
                                  additionalProperties: false
                                standard:
                                  type: object
                                  properties:
                                    priorityFeePerGasGwei:
                                      type: number
                                    maxFeePerGasGwei:
                                      type: number
                                    priorityFeePerGasWei:
                                      type: string
                                    maxFeePerGasWei:
                                      type: string
                                    transferNativeCost:
                                      type: number
                                  required:
                                  - priorityFeePerGasGwei
                                  - maxFeePerGasGwei
                                  - priorityFeePerGasWei
                                  - maxFeePerGasWei
                                  - transferNativeCost
                                  additionalProperties: false
                                fast:
                                  type: object
                                  properties:
                                    priorityFeePerGasGwei:
                                      type: number
                                    maxFeePerGasGwei:
                                      type: number
                                    priorityFeePerGasWei:
                                      type: string
                                    maxFeePerGasWei:
                                      type: string
                                    transferNativeCost:
                                      type: number
                                  required:
                                  - priorityFeePerGasGwei
                                  - maxFeePerGasGwei
                                  - priorityFeePerGasWei
                                  - maxFeePerGasWei
                                  - transferNativeCost
                                  additionalProperties: false
                              required:
                              - slow
                              - standard
                              - fast
                              additionalProperties: false
                              description: Priority-fee percentiles (slow=p25, standard=p50, fast=p75) over the trailing 4 blocks.
                            source:
                              type: object
                              properties:
                                provider:
                                  type: string
                                rpcEndpoint:
                                  type: string
                                method:
                                  type: string
                                license:
                                  type: string
                              required:
                              - provider
                              - rpcEndpoint
                              - method
                              - license
                              additionalProperties: false
                          required:
                          - chain
                          - block
                          - tiers
                          - source
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.gas-oracle
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: chain
        in: query
        required: true
        description: 'EVM chain to query: base | ethereum | polygon | arbitrum | optimism.'
        schema:
          type: string
          enum:
          - base
          - ethereum
          - polygon
          - arbitrum
          - optimism
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/global:
    get:
      tags:
      - Crypto
      summary: 'Whole-crypto-market overview: total market cap (USD), total'
      description: 'Whole-crypto-market overview: total market cap (USD), total 24h volume, 24h market-cap % change, Bitcoin + Ethereum dominance, count of active cryptocurrencies and markets. Source: CoinGecko.'
      operationId: crypto_global
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [global market overview]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            totalMarketCapUsd:
                              type: number
                              nullable: true
                            totalVolume24hUsd:
                              type: number
                              nullable: true
                            marketCapChange24hPct:
                              type: number
                              nullable: true
                            btcDominancePct:
                              type: number
                              nullable: true
                            ethDominancePct:
                              type: number
                              nullable: true
                            activeCryptocurrencies:
                              type: number
                              nullable: true
                            markets:
                              type: number
                              nullable: true
                          required:
                          - totalMarketCapUsd
                          - totalVolume24hUsd
                          - marketCapChange24hPct
                          - btcDominancePct
                          - ethDominancePct
                          - activeCryptocurrencies
                          - markets
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.global
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/hyperliquid-funding:
    get:
      tags:
      - Crypto
      summary: Live perp funding rates, open interest, and mark/oracle/mid
      description: 'Live perp funding rates, open interest, and mark/oracle/mid prices across 200+ Hyperliquid perpetuals (free/keyless). Each row: coin, hourly funding rate, open interest, mark/oracle/mid price, premium, prior-day price, 24h notional volume, max leverage. Filter by coin; sort by oi, volume, or funding. On-chain perp microstructure for funding-arb and OI signals.'
      operationId: crypto_hyperliquid-funding
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = perps.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            coin:
                              type: string
                              nullable: true
                            maxLeverage:
                              type: number
                              nullable: true
                            fundingHourly:
                              type: number
                              nullable: true
                            openInterest:
                              type: number
                              nullable: true
                            markPx:
                              type: number
                              nullable: true
                            oraclePx:
                              type: number
                              nullable: true
                            midPx:
                              type: number
                              nullable: true
                            premium:
                              type: number
                              nullable: true
                            prevDayPx:
                              type: number
                              nullable: true
                            dayNotionalVolume:
                              type: number
                              nullable: true
                          required:
                          - coin
                          - maxLeverage
                          - fundingHourly
                          - openInterest
                          - markPx
                          - oraclePx
                          - midPx
                          - premium
                          - prevDayPx
                          - dayNotionalVolume
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.hyperliquid-funding
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: coin
        in: query
        required: false
        description: Coin.
        schema:
          type: string
          maxLength: 40
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          enum:
          - oi
          - volume
          - funding
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 250
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/hyperliquid-predicted-funding:
    get:
      tags:
      - Crypto
      summary: Predicted next funding rates per coin across venues
      description: Predicted next funding rates per coin across venues (Hyperliquid + Binance/Bybit perps), free/keyless. For each coin, a list of venues with predicted funding rate, next funding time, and funding interval — for cross-venue funding-rate arbitrage. Filter by coin.
      operationId: crypto_hyperliquid-predicted-funding
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = coins with per-venue predicted funding.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            coin:
                              type: string
                              nullable: true
                            venues:
                              type: array
                              items:
                                type: object
                                properties:
                                  venue:
                                    type: string
                                  fundingRate:
                                    type: number
                                    nullable: true
                                  nextFundingTime:
                                    type: number
                                    nullable: true
                                  fundingIntervalHours:
                                    type: number
                                    nullable: true
                                required:
                                - venue
                                - fundingRate
                                - nextFundingTime
                                - fundingIntervalHours
                                additionalProperties: false
                          required:
                          - coin
                          - venues
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.hyperliquid-predicted-funding
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: coin
        in: query
        required: false
        description: Coin.
        schema:
          type: string
          maxLength: 40
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 250
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/kimchi-premium:
    get:
      tags:
      - Crypto
      summary: The "kimchi premium" - how much higher a crypto asset
      description: The "kimchi premium" — how much higher a crypto asset trades on Korean exchanges (Upbit, KRW) than its global USD price, as a percent. Computed as (Upbit KRW price / (global USD price × USD/KRW)) − 1. Pass symbol = ticker(s), comma-separated up to 10 (default BTC); supported majors include BTC, ETH, XRP, SOL, DOGE, ADA, TRX and more. Returns per symbol { krwPrice, usdPrice, usdKrw, globalUsdInKrw, premiumPct }. Per-symbol resilient (one unlisted symbol does not fail the rest); unresolved symbols are reported in meta.errors. Live blend of Upbit (KRW price) + CoinGecko (global USD) + ECB/Frankfurter (USD/KRW FX).
      operationId: crypto_kimchi-premium
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = per-symbol kimchi-premium rows; total = rows returned; meta.errors lists symbols that could not be resolved.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            symbol:
                              type: string
                            krwPrice:
                              type: number
                              description: Upbit KRW spot price.
                            usdPrice:
                              type: number
                              description: Global USD spot price (CoinGecko).
                            usdKrw:
                              type: number
                              description: USD/KRW reference FX rate (ECB).
                            globalUsdInKrw:
                              type: number
                              description: usdPrice * usdKrw — the global price expressed in KRW.
                            premiumPct:
                              type: number
                              description: (krwPrice / globalUsdInKrw - 1) * 100. Positive = Korea trades richer.
                          required:
                          - symbol
                          - krwPrice
                          - usdPrice
                          - usdKrw
                          - globalUsdInKrw
                          - premiumPct
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          usdKrw:
                            type: number
                          errors:
                            type: array
                            items:
                              type: object
                              properties:
                                symbol:
                                  type: string
                                error:
                                  type: string
                              required:
                              - symbol
                              - error
                              additionalProperties: false
                          asOf:
                            type: string
                        required:
                        - usdKrw
                        - errors
                        - asOf
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.kimchi-premium
      x-2s-version: null
      x-2s-price:
        usd: 0.012
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.012000'
        protocols:
        - x402: {}
      parameters:
      - name: symbol
        in: query
        required: false
        description: Comma-separated ticker symbols, up to 10 (default BTC). E.g. "BTC,ETH,XRP,SOL".
        schema:
          allOf:
          - anyOf:
            - not: {}
            - type: string
              maxLength: 120
            default: BTC
          - type: array
            items:
              type: string
              pattern: ^[A-Z0-9]{2,12}$
            minItems: 1
            maxItems: 10
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/markets:
    get:
      tags:
      - Crypto
      summary: Top cryptocurrencies by market cap with live price, market
      description: 'Top cryptocurrencies by market cap with live price, market cap, 24h volume, and 24h + 7d % change. Pass limit (1–100, default 20). Source: CoinGecko. For a single token use crypto.token-price; for the whole-market overview use crypto.global.'
      operationId: crypto_markets
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = top coins by market cap; total = count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            rank:
                              type: number
                              nullable: true
                            id:
                              type: string
                            symbol:
                              type: string
                            name:
                              type: string
                            priceUsd:
                              type: number
                              nullable: true
                            marketCapUsd:
                              type: number
                              nullable: true
                            volume24hUsd:
                              type: number
                              nullable: true
                            change24hPct:
                              type: number
                              nullable: true
                            change7dPct:
                              type: number
                              nullable: true
                          required:
                          - rank
                          - id
                          - symbol
                          - name
                          - priceUsd
                          - marketCapUsd
                          - volume24hUsd
                          - change24hPct
                          - change7dPct
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.markets
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/nft:
    get:
      tags:
      - Crypto
      summary: Live ERC-721 NFT read (Base, Ethereum, Polygon, Arbitrum
      description: 'Live ERC-721 NFT read (Base, Ethereum, Polygon, Arbitrum, Optimism; keyless). Given a contract + tokenId: returns current owner, collection name/symbol, and tokenURI (IPFS auto-resolved to a gateway URL). Pass metadata=1 to also fetch and normalize the token''s JSON metadata (name, description, image, attributes). For NFT provenance, ownership checks, and gallery rendering.'
      operationId: crypto_nft
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [one NFT read].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chain:
                              type: string
                            contract:
                              type: string
                            tokenId:
                              type: string
                            owner:
                              nullable: true
                            collectionName:
                              nullable: true
                            collectionSymbol:
                              nullable: true
                            tokenURI:
                              type: string
                              nullable: true
                            metadata:
                              type: object
                              properties:
                                name:
                                  nullable: true
                                description:
                                  nullable: true
                                image:
                                  type: string
                                  nullable: true
                                attributes:
                                  type: array
                                  items: {}
                                  nullable: true
                              required:
                              - image
                              - attributes
                              additionalProperties: false
                              nullable: true
                          required:
                          - chain
                          - contract
                          - tokenId
                          - tokenURI
                          - metadata
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.nft
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: address
        in: query
        required: true
        description: NFT contract address.
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - name: tokenId
        in: query
        required: true
        description: Token id (decimal).
        schema:
          type: string
          pattern: ^\d+$
          maxLength: 80
      - name: chain
        in: query
        required: false
        description: Default ethereum.
        schema:
          type: string
          enum:
          - base
          - ethereum
          - polygon
          - arbitrum
          - optimism
      - name: metadata
        in: query
        required: false
        description: 1 to also fetch token JSON metadata.
        schema:
          type: string
          enum:
          - '0'
          - '1'
          - 'true'
          - 'false'
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/nft-security:
    get:
      tags:
      - Crypto
      summary: NFT collection risk screening via GoPlus (free, keyless)
      description: 'NFT collection risk screening via GoPlus (free, keyless). For an ERC-721/1155 contract: verification/trust-list status, open-source + proxy flags, privileged-minting, restricted-approval, transfer-without-approval, metadata-frozen and self-destruct risks, plus owner count and volume stats. Screen a collection before minting, buying, or approving — complements crypto.nft (reads) and crypto.token-safety.'
      operationId: crypto_nft-security
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [one NFT-security report].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chainId:
                              type: string
                            address:
                              type: string
                            nftName:
                              nullable: true
                            nftSymbol:
                              nullable: true
                            verified:
                              type: boolean
                              nullable: true
                            onTrustList:
                              type: boolean
                              nullable: true
                            isOpenSource:
                              type: boolean
                              nullable: true
                            isProxy:
                              type: boolean
                              nullable: true
                            privilegedMinting:
                              type: boolean
                              nullable: true
                            restrictedApproval:
                              type: boolean
                              nullable: true
                            transferWithoutApproval:
                              type: boolean
                              nullable: true
                            metadataFrozen:
                              type: boolean
                              nullable: true
                            selfDestruct:
                              type: boolean
                              nullable: true
                            ownerNumber:
                              type: number
                              nullable: true
                            totalVolume:
                              type: number
                              nullable: true
                            tradedVolume24h:
                              type: number
                              nullable: true
                            averagePrice24h:
                              type: number
                              nullable: true
                            creatorAddress:
                              nullable: true
                          required:
                          - chainId
                          - address
                          - verified
                          - onTrustList
                          - isOpenSource
                          - isProxy
                          - privilegedMinting
                          - restrictedApproval
                          - transferWithoutApproval
                          - metadataFrozen
                          - selfDestruct
                          - ownerNumber
                          - totalVolume
                          - tradedVolume24h
                          - averagePrice24h
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.nft-security
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: address
        in: query
        required: true
        description: NFT contract address.
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - name: chainId
        in: query
        required: false
        description: EVM chain id (default 1 = Ethereum).
        schema:
          type: integer
          exclusiveMinimum: true
          minimum: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/stablecoins:
    get:
      tags:
      - Crypto
      summary: Stablecoin supply leaderboard (via DefiLlama
      description: 'Stablecoin supply leaderboard (via DefiLlama, free/keyless): the largest stablecoins by circulating USD, with peg type (USD/EUR/…), peg mechanism (fiat-backed, crypto-backed, algorithmic), and current price. For tracking stablecoin market share and de-peg risk.'
      operationId: crypto_stablecoins
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = stablecoins by circulating USD desc.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              nullable: true
                            symbol:
                              nullable: true
                            pegType:
                              nullable: true
                            pegMechanism:
                              nullable: true
                            price:
                              type: number
                              nullable: true
                            circulatingUsd:
                              type: number
                              nullable: true
                          required:
                          - price
                          - circulatingUsd
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.stablecoins
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/token-info:
    get:
      tags:
      - Crypto
      summary: On-chain token metrics by contract address (via
      description: 'On-chain token metrics by contract address (via GeckoTerminal, free/keyless): name, symbol, decimals, on-chain USD price, FDV, market cap, total reserve in USD, 24h volume, total + normalized supply, image, and CoinGecko id. Distinct from crypto.token-price (CoinGecko aggregate spot) — this is DEX-derived on-chain data for any token across 100+ networks.'
      operationId: crypto_token-info
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [token info].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            address:
                              nullable: true
                            name:
                              nullable: true
                            symbol:
                              nullable: true
                            decimals:
                              type: number
                              nullable: true
                            imageUrl:
                              nullable: true
                            coingeckoCoinId:
                              nullable: true
                            priceUsd:
                              type: number
                              nullable: true
                            fdvUsd:
                              type: number
                              nullable: true
                            marketCapUsd:
                              type: number
                              nullable: true
                            totalReserveUsd:
                              type: number
                              nullable: true
                            volume24hUsd:
                              type: number
                              nullable: true
                            totalSupply:
                              type: string
                              nullable: true
                            normalizedTotalSupply:
                              type: string
                              nullable: true
                          required:
                          - decimals
                          - priceUsd
                          - fdvUsd
                          - marketCapUsd
                          - totalReserveUsd
                          - volume24hUsd
                          - totalSupply
                          - normalizedTotalSupply
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.token-info
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: network
        in: query
        required: true
        description: Network slug, e.g. eth, bsc, base, solana.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: address
        in: query
        required: true
        description: Token contract address.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/token-metadata:
    get:
      tags:
      - Crypto
      summary: Live on-chain token metadata for an ERC-20 or ERC-721
      description: Live on-chain token metadata for an ERC-20 or ERC-721 contract (Base, Ethereum, Polygon, Arbitrum, Optimism; keyless). Returns name, symbol, decimals, detected standard, and total supply (raw + formatted). The authoritative read straight from the contract — complements crypto.token-price and crypto.contract (ABI/source).
      operationId: crypto_token-metadata
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [one token-metadata object].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chain:
                              type: string
                            contract:
                              type: string
                            name:
                              nullable: true
                            symbol:
                              nullable: true
                            decimals:
                              type: number
                              nullable: true
                            standard:
                              type: string
                            totalSupply:
                              type: string
                              nullable: true
                            totalSupplyFormatted:
                              type: string
                              nullable: true
                          required:
                          - chain
                          - contract
                          - decimals
                          - standard
                          - totalSupply
                          - totalSupplyFormatted
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.token-metadata
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: address
        in: query
        required: true
        description: Token contract address.
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - name: chain
        in: query
        required: false
        description: Default base.
        schema:
          type: string
          enum:
          - base
          - ethereum
          - polygon
          - arbitrum
          - optimism
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/token-price:
    get:
      tags:
      - Crypto
      summary: Current spot price and market data for crypto assets
      description: Current spot price and market data for crypto assets. Pass ids as comma-separated CoinGecko asset ids (e.g. bitcoin, ethereum, solana, usd-coin — lowercase id, not ticker symbol; up to 25 per call) and optionally vs (comma-separated fiat/crypto quote currencies, default usd). Returns per-asset price, market cap, 24h volume, and 24h percent change, plus the data timestamp. Live market data past any training cutoff. Price data by CoinGecko.
      operationId: crypto_token-price
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = per-asset spot price/market cap/24h volume/24h change per quote currency; total = null (no upstream count); meta.asOf is the data timestamp.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: CoinGecko asset id.
                            quotes:
                              type: object
                              additionalProperties:
                                type: object
                                properties:
                                  price:
                                    type: number
                                    nullable: true
                                  marketCap:
                                    type: number
                                    nullable: true
                                  volume24h:
                                    type: number
                                    nullable: true
                                  change24hPct:
                                    type: number
                                    nullable: true
                                required:
                                - price
                                - marketCap
                                - volume24h
                                - change24hPct
                                additionalProperties: false
                          required:
                          - id
                          - quotes
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          asOf:
                            type: string
                        required:
                        - asOf
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.token-price
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: ids
        in: query
        required: true
        description: Comma-separated CoinGecko asset ids (lowercase), e.g. "bitcoin,ethereum". Max 25.
        schema:
          allOf:
          - type: string
            minLength: 2
            maxLength: 600
          - type: array
            items:
              type: string
              pattern: ^[a-z0-9-]+$
            minItems: 1
            maxItems: 25
      - name: vs
        in: query
        required: false
        description: Vs.
        schema:
          allOf:
          - anyOf:
            - not: {}
            - type: string
              maxLength: 60
            default: usd
          - type: array
            items:
              type: string
              pattern: ^[a-z]{2,10}$
            minItems: 1
            maxItems: 5
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/token-safety:
    get:
      tags:
      - Crypto
      summary: Token honeypot & rug-pull risk screen (via GoPlus
      description: Token honeypot & rug-pull risk screen (via GoPlus, free/keyless). For an ERC-20 on any EVM chain, returns honeypot flag, buy/sell tax, open-source/proxy/mintable status, hidden-owner / take-back-ownership / selfdestruct / external-call risks, blacklist/whitelist/anti-whale flags, holder count, and owner/creator concentration. Essential pre-trade safety check for agents — the security layer competitors charge for.
      operationId: crypto_token-safety
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [token safety report].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chainId:
                              type: string
                            address:
                              type: string
                            tokenName:
                              nullable: true
                            tokenSymbol:
                              nullable: true
                            isHoneypot:
                              type: boolean
                              nullable: true
                            buyTax:
                              type: number
                              nullable: true
                            sellTax:
                              type: number
                              nullable: true
                            isOpenSource:
                              type: boolean
                              nullable: true
                            isProxy:
                              type: boolean
                              nullable: true
                            isMintable:
                              type: boolean
                              nullable: true
                            canTakeBackOwnership:
                              type: boolean
                              nullable: true
                            hiddenOwner:
                              type: boolean
                              nullable: true
                            selfdestruct:
                              type: boolean
                              nullable: true
                            externalCall:
                              type: boolean
                              nullable: true
                            isBlacklisted:
                              type: boolean
                              nullable: true
                            isWhitelisted:
                              type: boolean
                              nullable: true
                            isAntiWhale:
                              type: boolean
                              nullable: true
                            slippageModifiable:
                              type: boolean
                              nullable: true
                            isInDex:
                              type: boolean
                              nullable: true
                            isInCex:
                              type: boolean
                              nullable: true
                            holderCount:
                              type: number
                              nullable: true
                            ownerAddress:
                              nullable: true
                            creatorAddress:
                              nullable: true
                            ownerPercent:
                              type: number
                              nullable: true
                            creatorPercent:
                              type: number
                              nullable: true
                          required:
                          - chainId
                          - address
                          - isHoneypot
                          - buyTax
                          - sellTax
                          - isOpenSource
                          - isProxy
                          - isMintable
                          - canTakeBackOwnership
                          - hiddenOwner
                          - selfdestruct
                          - externalCall
                          - isBlacklisted
                          - isWhitelisted
                          - isAntiWhale
                          - slippageModifiable
                          - isInDex
                          - isInCex
                          - holderCount
                          - ownerPercent
                          - creatorPercent
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.token-safety
      x-2s-version: null
      x-2s-price:
        usd: 0.004998
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004998'
        protocols:
        - x402: {}
      parameters:
      - name: chainId
        in: query
        required: true
        description: EVM chain id, e.g. 1 (Ethereum), 56 (BSC), 137 (Polygon), 8453 (Base).
        schema:
          type: string
          minLength: 1
          maxLength: 20
      - name: address
        in: query
        required: true
        description: Street address or full address string.
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/token-transfers:
    get:
      tags:
      - Crypto
      summary: ERC-20 token transfer history for an Ethereum address (via
      description: 'ERC-20 token transfer history for an Ethereum address (via Etherscan V2). Each transfer: hash, block, timestamp, from/to, token contract, name, symbol, decimals, and value (raw + decimal-adjusted). Optionally filter to one token contract. Paginate with page + offset. Defaults to Ethereum mainnet; other EVM chains by chainId where upstream coverage allows. Trace what tokens a wallet sent/received.'
      operationId: crypto_token-transfers
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = ERC-20 transfers.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            hash:
                              nullable: true
                            blockNumber:
                              type: number
                              nullable: true
                            timestamp:
                              type: string
                              nullable: true
                            from:
                              nullable: true
                            to:
                              nullable: true
                            contractAddress:
                              nullable: true
                            tokenName:
                              nullable: true
                            tokenSymbol:
                              nullable: true
                            tokenDecimal:
                              type: number
                              nullable: true
                            valueRaw:
                              type: string
                              nullable: true
                            value:
                              type: number
                              nullable: true
                          required:
                          - blockNumber
                          - timestamp
                          - tokenDecimal
                          - valueRaw
                          - value
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.token-transfers
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: chainId
        in: query
        required: false
        description: EVM chain id; defaults to 1 (Ethereum). Other chains require upstream multichain coverage.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: address
        in: query
        required: true
        description: Street address or full address string.
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - name: contractAddress
        in: query
        required: false
        description: Filter to one ERC-20 contract.
        schema:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          enum:
          - asc
          - desc
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/trending:
    get:
      tags:
      - Crypto
      summary: The most-searched trending cryptocurrencies on CoinGecko
      description: 'The most-searched trending cryptocurrencies on CoinGecko right now (last 24h), each with symbol, name, market-cap rank, and price. A real-time popularity/attention signal. Source: CoinGecko.'
      operationId: crypto_trending
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = trending coins (most-searched first); total = count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            symbol:
                              type: string
                            name:
                              type: string
                            marketCapRank:
                              type: number
                              nullable: true
                            priceUsd:
                              type: number
                              nullable: true
                          required:
                          - id
                          - symbol
                          - name
                          - marketCapRank
                          - priceUsd
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.trending
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/tx:
    get:
      tags:
      - Crypto
      summary: Live EVM transaction status and receipt lookup
      description: 'Live EVM transaction status and receipt lookup. Give a transaction hash + chain and get back whether it mined successfully, reverted, or is still pending in the mempool, plus block number, confirmations, timestamp, sender and recipient, value transferred (native unit), gas used, effective gas price, total fee paid, any contract created, and event-log count. Chains: base, ethereum, polygon, arbitrum, optimism. Real-time post-training chain state — use it to confirm a payment settled, detect a reverted transaction, or wait for confirmations before acting. Unknown hash returns 404. Sibling of /api/crypto/gas-oracle (fees) and /api/crypto/address-validate (format).'
      operationId: crypto_tx
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [the transaction] with status (success | reverted | pending), block, confirmations, from/to, value (native), gasUsed, effectiveGasPriceGwei, feeNative, contractAddress, logCount; total = 1. 404 if the hash is unknown on that chain.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            chain:
                              type: object
                              properties:
                                key:
                                  type: string
                                name:
                                  type: string
                                chainId:
                                  type: number
                                nativeSymbol:
                                  type: string
                              required:
                              - key
                              - name
                              - chainId
                              - nativeSymbol
                              additionalProperties: false
                            hash:
                              type: string
                            status:
                              type: string
                              enum:
                              - success
                              - reverted
                              - pending
                            mined:
                              type: boolean
                            blockNumber:
                              type: number
                              nullable: true
                              description: Null while pending.
                            blockTimestamp:
                              type: number
                              nullable: true
                              description: Block time, Unix ms; null while pending.
                            confirmations:
                              type: number
                              description: Blocks on top of the tx block, inclusive of its own; 0 while pending.
                            from:
                              type: string
                            to:
                              type: string
                              nullable: true
                              description: Null for contract-creation transactions.
                            contractAddress:
                              type: string
                              nullable: true
                              description: Contract created, if this was a contract-creation tx.
                            nonce:
                              type: number
                            valueNative:
                              type: string
                              description: Value transferred in the chain native unit (decimal string).
                            valueWei:
                              type: string
                            gasUsed:
                              type: string
                              nullable: true
                              description: Gas units consumed; null while pending.
                            effectiveGasPriceGwei:
                              type: string
                              nullable: true
                            feeNative:
                              type: string
                              nullable: true
                              description: Total fee = gasUsed × effectiveGasPrice, native unit; null while pending.
                            logCount:
                              type: number
                              nullable: true
                              description: Event logs emitted; null while pending.
                          required:
                          - chain
                          - hash
                          - status
                          - mined
                          - blockNumber
                          - blockTimestamp
                          - confirmations
                          - from
                          - to
                          - contractAddress
                          - nonce
                          - valueNative
                          - valueWei
                          - gasUsed
                          - effectiveGasPriceGwei
                          - feeNative
                          - logCount
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.tx
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: chain
        in: query
        required: true
        description: 'EVM chain to query: base | ethereum | polygon | arbitrum | optimism.'
        schema:
          type: string
          enum:
          - base
          - ethereum
          - polygon
          - arbitrum
          - optimism
      - name: hash
        in: query
        required: true
        description: 'Transaction hash: 0x followed by 64 hex characters.'
        schema:
          type: string
          pattern: ^0x[0-9a-fA-F]{64}$
      - $ref: '#/components/parameters/TrialMode'
  /api/crypto/vrf:
    get:
      tags:
      - Crypto
      summary: Verifiable random function - deterministic, publicly
      description: 'Verifiable random function — deterministic, publicly verifiable randomness bound to your seed and signed by the 2s key. proof = deterministic EIP-191 signature over the seed (same seed always yields the same proof, so the outcome cannot be re-rolled or cherry-picked); random = keccak256(proof), a uniform 32-byte value. Returns the seed, signed message, proof, signer address, random (hex + uint + float in [0,1)). Verify offline: recover the signer from (message, proof) and confirm keccak256(proof) == random. For provably-fair draws, lotteries, sortition, and tie-breaks between agents.'
      operationId: crypto_vrf
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [one VRF output with verifiable proof].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            seed:
                              type: string
                            signer:
                              type: string
                            alg:
                              type: string
                            version:
                              type: string
                            message:
                              type: string
                            proof:
                              type: string
                            random:
                              type: string
                            randomUint:
                              type: string
                            randomFloat:
                              type: number
                          required:
                          - seed
                          - signer
                          - alg
                          - version
                          - message
                          - proof
                          - random
                          - randomUint
                          - randomFloat
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: crypto.vrf
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: seed
        in: query
        required: true
        description: Any seed string — a request id, block hash, commitment, etc.
        schema:
          type: string
          minLength: 1
          maxLength: 256
      - $ref: '#/components/parameters/TrialMode'
components:
  schemas:
    Source:
      type: object
      description: 'Provenance of the data: upstream provider, source URL, and license.'
      properties:
        provider:
          type: string
          description: Upstream data provider.
        url:
          type: string
          description: Source URL or documentation link.
        license:
          type: string
          description: License / usage terms for the data.
    CallMeta:
      type: object
      description: Per-call meta envelope — endpoint id, cost, caller kind, settlement details.
    X402PaymentRequiredV2:
      type: object
      description: x402 v2 PaymentRequired envelope. Pick any entry from accepts[], sign for that rail, retry with the PAYMENT-SIGNATURE header.
      required:
      - x402Version
      - accepts
      properties:
        x402Version:
          type: integer
          const: 2
        error:
          type: string
          description: Human-readable reason payment is required.
        resource:
          type: string
          description: The resource URL being purchased.
        accepts:
          type: array
          description: Payment requirement options, one per supported network (Base USDC, Solana USDC).
          items:
            type: object
            required:
            - scheme
            - network
            - amount
            - asset
            - payTo
            - maxTimeoutSeconds
            properties:
              scheme:
                type: string
                enum:
                - exact
              network:
                type: string
                description: CAIP-2 network id, e.g. "eip155:8453" (Base) or "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp".
              amount:
                type: string
                description: Price in atomic asset units (USDC has 6 decimals).
              asset:
                type: string
                description: Asset contract address / mint.
              payTo:
                type: string
                description: Treasury address to pay.
              maxTimeoutSeconds:
                type: integer
              extra:
                type: object
                description: 'Rail-specific extras (EVM: EIP-712 domain name/version; Solana: feePayer).'
                additionalProperties: true
        extensions:
          type: object
          description: Optional discovery metadata (e.g. bazaar input/output schemas).
          additionalProperties: true
  responses:
    PaymentRequired:
      description: Payment required. Body contains the x402 PaymentRequirements envelope with a multi-network accepts array; the per-call price is in accepts[].amount (and on the operation as x-2s-price). Sign for whichever rail you hold USDC on (EIP-3009 for Base, partial SPL transfer for Solana) and retry with the PAYMENT-SIGNATURE header (X-PAYMENT also accepted for v1 clients).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/X402PaymentRequiredV2'
    UpstreamError:
      description: Upstream provider error.
    MethodNotAllowed:
      description: Method not allowed — see `Allow` header for the supported method.
    ServerError:
      description: Internal server error.
    BadRequest:
      description: Bad request — invalid parameters.
  parameters:
    TrialMode:
      name: trial
      in: query
      required: false
      description: 'Try before you buy. Set to 1 for one free real call per endpoint per hour — no wallet or payment needed — to verify the endpoint before paying. Equivalent to sending the "X-2s-Trial: 1" request header. Works on every endpoint.'
      schema:
        type: integer
        enum:
        - 1
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: 'x402 protocol v2: base64-encoded PaymentPayload. Call any paid endpoint without auth to receive a 402 with a multi-network PaymentRequirements envelope. Sign for either rail: EIP-3009 transferWithAuthorization (Base USDC) OR a partial SPL token transfer (Solana USDC). Retry with PAYMENT-SIGNATURE header. X-PAYMENT is also accepted for v1 buyer clients. See https://x402.org.'