Coil Paid reads API

openapi: 3.2.0
info:
  title: Coil Agent Paid reads API
  version: 1.2.0
  description: 'A trading desk''s discipline for your AI agent: when to trade, when to wait and when to sit in cash, plus the scores to act on. Market data and trading signals for AI agents, paid per call in USDC — no account, no API key, no signup. New here? Start with GET /api/crypto/gate — $0.001, the cheapest answer we sell and the most common first call: is crypto risk-on right now. Paid endpoints run from $0.001 to $0.25 per read, plus the published research studies (free index: GET /api/research), plus a $0.25 one-hour Coil Live session: market regime verdicts, 0-100 opportunity / entry-timing / hold-strength scores per name, ranked buy lists, sector and macro rotation, day-trade state maps, per-symbol hold state, a point-in-time archive, and a 24/7 crypto board — across 650+ names (S&P 500, Nasdaq-100, macro ETFs) and 81 Robinhood-tradable crypto pairs. Equities re-score about every 5 minutes through the US market day; crypto runs around the clock. Every response is timestamped (computed_at) and carries an on-chain settlement receipt.


    FREE FIRST, no payment and no key: a live top-3 preview per book (/api/board/agent?preview=1, identical schema), a sample of the board (top 3 per book, headline fields) one market day delayed over MCP (claude mcp add --transport http coil https://mcp.coil.trade/mcp), one complete committed day from the append-only log, our own forward-return audit (/api/board/signal-audit) and a sha256 commitment log (/api/board/proof). A free key or a wallet sign-in (SIWX) unlocks ~25 live calls/day on the cheap reads.


    Impersonal research publication — identical for every buyer, not individualized investment advice; scores describe historical and technical structure, not future returns. Markets can lose money; crypto is highly volatile and can lose value rapidly, including total loss.'
  x-guidance: 'The reads follow a trading desk''s routine, top-down: the gate first (is the market worth trading today; on a cash reading nothing new opens), then where money is moving, then the set-ups with their entry windows, then one name before any buy, and the hold state of what you own (a broken trend ends the thesis; exits come before entries). Start here: /api/crypto/gate ($0.001) is the cheapest answer we sell and the most common first call — is crypto risk-on right now, straight from the BTC 200-day master gate. /api/board/regime ($0.005) asks the same question of the equity tape and /api/board/indices ($0.005) gives the index ladder; those two are the usual next calls. Then drill in. If the regime is favorable, /api/board/buylist ($0.05) returns today''s ranked candidates, or /api/board/name?sym=NVDA ($0.005, up to 10 symbols) scores tickers you hold. /api/board/hold?sym= ($0.005) says whether a position''s trend state is intact. /api/crypto/day ($0.005) is the 24/7 board for 81 Robinhood-tradable coins. Call any paid path with no payment header to get HTTP 402 carrying BOTH x402 v2 requirements (also base64 in PAYMENT-REQUIRED) and an MPP ''WWW-Authenticate: Payment'' challenge; pay on Base, Solana or Algorand and the same request returns JSON plus an on-chain receipt. 402 amounts are atomic units (USDC 6dp: $0.005 = "5000"); OpenAPI price.amount is decimal USD. Free first: ?preview=1, the delayed MCP server, /api/board/signal-audit, /api/board/proof; poll /api/board/state (free) and buy only when its hash moves. Rank by opp_pct; read the book regime before acting on any name score. BEHAVIOUR LAYER: when to call, when to come back and when to STOP is the skill at https://coil.trade/skills/coil-board/SKILL.md (an agent reading only this spec never saw it before). ALGORAND FEES ARE SPONSORED: both Algorand rails carry a feePayer, so you need zero ALGO to pay — Base and Solana require gas tokens. That rail is easiest for a wallet holding only USDC.'
  contact:
    email: support@coil.trade
    url: https://coil.trade/agents
  x-polling-contract: Every response (paid AND the free preview) carries a freshness block — market_open, data_age_seconds, next_refresh_at, and a plain-language poll_hint — plus the same values in the X-Coil-Market-Open / X-Coil-Next-Refresh / X-Coil-Data-Age response headers. It tells you when the board will actually change, so you poll only when there is new data instead of re-buying an identical payload. When the US market is shut it says so and gives the next session time. Market holidays are not modelled (a holiday reads as open while the board simply will not advance — data_age_seconds still reveals it).
servers:
- url: https://coil.trade
tags:
- name: Paid reads
paths:
  /stocks/{symbol}/full:
    get:
      operationId: getStockFull
      summary: Coil Single-Name Score as a page ($0.005 per read) — the paid twin of…
      tags:
      - Paid reads
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.005000'
        protocols:
        - x402: {}
        - mpp:
            method: usdc
            intent: charge
            currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        description: 'Buy one stock''s full score read (x402, USDC on Base) — x402 ''exact'' charge, USDC on Base (eip155:8453). Amount in 6-decimal base units. Live offer document: GET https://coil.trade/api'
        offers:
        - intent: charge
          method: x402
          amount: '5000'
          currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
          description: 'Buy one stock''s full score read (x402, USDC on Base) — x402 ''exact'' charge, USDC on Base (eip155:8453). Amount in 6-decimal base units. Live offer document: GET https://coil.trade/api'
        - intent: charge
          method: x402
          amount: '5000'
          currency: '31566704'
          description: 'Buy one stock''s full score read (x402, USDC on Base) — x402 ''exact'' charge, USDCa on Algorand mainnet. Amount in 6-decimal base units. Live offer document: GET https://coil.trade/api'
        - intent: charge
          method: x402
          amount: '5000'
          currency: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
          description: 'Buy one stock''s full score read (x402, USDC on Base) — x402 ''exact'' charge, USDC on Solana mainnet. Amount in 6-decimal base units. Live offer document: GET https://coil.trade/api'
        mpp:
          method: usdc
          intent: charge
          challenge: 'WWW-Authenticate: Payment'
          credential: 'Authorization: Payment'
          network: eip155:8453
        nanopayments:
          rail: circle-gateway
          scheme: exact
          network: eip155:8453
          select: the accepts entry with extra.name=GatewayWalletBatched
          note: Gasless batched USDC from a unified Circle Gateway balance — sign with @circle-fin/x402-batching (registerBatchScheme); settles offchain to the seller's Gateway balance.
      responses:
        '402':
          description: Payment Required — the base product's x402 v2 payment requirements in the JSON body and the PAYMENT-REQUIRED header (USDC on Base, Solana or Algorand). An input the site does not hold is a free 404, never a 402.
        '200':
          description: 'The same read GET /api/board/name?sym={symbol} sells, as a readable page: markdown by default, HTML with Accept: text/html, JSON with Accept: application/json. Served only after the payment settles. Settlement receipt in the PAYMENT-RESPONSE header.'
          content:
            text/markdown:
              schema:
                type: string
            text/html:
              schema:
                type: string
            application/json:
              schema:
                type: object
      parameters:
      - name: symbol
        in: path
        required: true
        schema:
          type: string
        example: NVDA
        description: An upper-case ticker the free page /stocks/{symbol} serves (for example NVDA, BRK-B).
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          type: string
        description: 'x402 v2 payment: base64 of the signed payment payload. Send this OR X-PAYMENT (v1 name) — omit both to receive the 402 challenge.'
      - name: X-PAYMENT
        in: header
        required: false
        schema:
          type: string
        description: x402 v1 payment header — the v1 dialect's name for PAYMENT-SIGNATURE. Accepted for backwards compatibility with v1 clients.
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
        description: 'MPP credential: `Payment <base64 credential>` answering the WWW-Authenticate: Payment challenge on the 402 (method usdc, intent charge).'
      description: 'A paid read for agents: the single-name read /api/board/name sells, for one symbol, at the same price, on the same rails, with the same data. The free page /stocks/{symbol} is open to everyone and unchanged; this page is noindex, nofollow and noarchive. A symbol the free page does not serve is a free 404.'
      security:
      - x402: []
      - mpp: []
  /board/{date}/full:
    get:
      operationId: getBoardDayFull
      summary: Coil Point-in-Time Scores as a page ($0.05 per read) — the paid twin of…
      tags:
      - Paid reads
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.050000'
        protocols:
        - x402: {}
        - mpp:
            method: usdc
            intent: charge
            currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        description: 'Buy point-in-time published scores for a date (x402) — x402 ''exact'' charge, USDC on Base (eip155:8453). Amount in 6-decimal base units. Live offer document: GET https://coil.trade/api Priced on the guarantee, not the bytes: $0.05 buys an as-published, sha256-committed, never-revised snapshot of a past day, verifiable against the free /api/board/proof commitment log. The same-day scores are cheaper on the live endpoints; you are paying for immutability and lookahead-bias-free history.'
        offers:
        - intent: charge
          method: x402
          amount: '50000'
          currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
          description: 'Buy point-in-time published scores for a date (x402) — x402 ''exact'' charge, USDC on Base (eip155:8453). Amount in 6-decimal base units. Live offer document: GET https://coil.trade/api'
        - intent: charge
          method: x402
          amount: '50000'
          currency: '31566704'
          description: 'Buy point-in-time published scores for a date (x402) — x402 ''exact'' charge, USDCa on Algorand mainnet. Amount in 6-decimal base units. Live offer document: GET https://coil.trade/api'
        - intent: charge
          method: x402
          amount: '50000'
          currency: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
          description: 'Buy point-in-time published scores for a date (x402) — x402 ''exact'' charge, USDC on Solana mainnet. Amount in 6-decimal base units. Live offer document: GET https://coil.trade/api'
        mpp:
          method: usdc
          intent: charge
          challenge: 'WWW-Authenticate: Payment'
          credential: 'Authorization: Payment'
          network: eip155:8453
        nanopayments:
          rail: circle-gateway
          scheme: exact
          network: eip155:8453
          select: the accepts entry with extra.name=GatewayWalletBatched
          note: Gasless batched USDC from a unified Circle Gateway balance — sign with @circle-fin/x402-batching (registerBatchScheme); settles offchain to the seller's Gateway balance.
        price_basis: 'Priced on the guarantee, not the bytes: $0.05 buys an as-published, sha256-committed, never-revised snapshot of a past day, verifiable against the free /api/board/proof commitment log. The same-day scores are cheaper on the live endpoints; you are paying for immutability and lookahead-bias-free history.'
      responses:
        '402':
          description: Payment Required — the base product's x402 v2 payment requirements in the JSON body and the PAYMENT-REQUIRED header (USDC on Base, Solana or Algorand). An input the site does not hold is a free 404, never a 402.
        '200':
          description: 'The same day GET /api/board/asof?date={date} sells, as a readable page: markdown by default, HTML with Accept: text/html, JSON with Accept: application/json. Served only after the payment settles. Settlement receipt in the PAYMENT-RESPONSE header.'
          content:
            text/markdown:
              schema:
                type: string
            text/html:
              schema:
                type: string
            application/json:
              schema:
                type: object
      parameters:
      - name: date
        in: path
        required: true
        schema:
          type: string
          format: date
        example: '2026-07-21'
        description: 'An archived publish date, YYYY-MM-DD, from the list GET /api/board/asof (free sample: /api/board/asof?sample=1).'
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          type: string
        description: 'x402 v2 payment: base64 of the signed payment payload. Send this OR X-PAYMENT (v1 name) — omit both to receive the 402 challenge.'
      - name: X-PAYMENT
        in: header
        required: false
        schema:
          type: string
        description: x402 v1 payment header — the v1 dialect's name for PAYMENT-SIGNATURE. Accepted for backwards compatibility with v1 clients.
      - name: Authorization
        in: header
        required: false
        schema:
          type: string
        description: 'MPP credential: `Payment <base64 credential>` answering the WWW-Authenticate: Payment challenge on the 402 (method usdc, intent charge).'
      description: 'A paid read for agents: the as-published scores /api/board/asof sells for one archived date, at the same price, on the same rails, with the same data. This page is noindex, nofollow and noarchive. A date that is not in the archive is a free 404.'
      security:
      - x402: []
      - mpp: []
components:
  securitySchemes:
    licenseKey:
      type: apiKey
      in: header
      name: X-License-Key
      description: Gumroad license key for a Coil subscription. Coil Live ($49/mo or $419/yr) unlocks /api/live/*; the Coil Scanner key ($19/mo) unlocks the live board endpoints. Sent as a raw header value, no scheme prefix.
    siwx:
      type: apiKey
      in: header
      name: X-Coil-Key
      description: 'Wallet auth, two interoperable lanes. (1) STANDARD x402 SIWX extension (docs.x402.org/extensions/sign-in-with-x): every 402 declares extensions[''sign-in-with-x''] with nonce/domain/uri and supportedChains (eip191 + ed25519); construct the CAIP-122/SIWE message, sign with the wallet, send base64 {message, signature, chainId, type} as the SIGN-IN-WITH-X header — the free-tier products serve directly, no mint step. (2) KEY-MINT convenience: GET /api/auth/nonce?address=&chain=base|solana|algorand, sign, POST /api/auth/verify to mint a durable coilwallet_ key sent as X-Coil-Key. Both grant the same free tier (25 calls/day on regime, indices, movers, crypto gate, crypto night, tradfi-risk, hold state). Signatures are messages, not transactions — no funds move.'
    x402:
      type: apiKey
      in: header
      name: X-PAYMENT
      description: x402 pay-per-call. Call with no payment header to receive HTTP 402 carrying payment requirements (also base64 in PAYMENT-REQUIRED), pay on Base, Solana or Algorand in USDC, then repeat the request with the signed payload base64 in X-PAYMENT. No account, no API key, no signup. See https://coil.trade/agents
    mpp:
      type: http
      scheme: Payment
      description: 'Machine Payment Protocol. The 402 carries a `WWW-Authenticate: Payment` challenge (method=usdc); answer it on the standard Authorization header as `Authorization: Payment <base64url(JSON{challenge, payload})>` — NOT on a custom header. x402 is the alternative rail and uses X-PAYMENT instead.'
    coilKey:
      type: apiKey
      in: header
      name: X-Coil-Key
      description: Free key (POST /api/key, instant, no card) or a SIWX wallet sign-in. Opens the cheap slices — regime, indices, movers, crypto gate, the overnight crypto read, tradfi-risk and hold state — for 25 calls/day per key without any payment. Endpoints listing coilKey alongside x402 are reachable EITHER way.