Coil Verification API

openapi: 3.2.0
info:
  title: Coil Agent Verification 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: Verification
  description: Free, before any payment — the append-only commitment log, the forward-return audit of our own scores, and the engine's record vs SPY/QQQ. Check the publisher before trusting it.
paths:
  /api/perf:
    get:
      operationId: getEngineRecord
      summary: FREE — the engine's record vs SPY and QQQ
      description: 'Engine-only, since inception: Cumulative P&L on starting capital, net of deposits (funding-adjusted), with its thin-sample note. Omitted (null) rather than estimated when unavailable. No payment, no key.'
      responses:
        '200':
          description: Record + method + link to the proof log
      security: []
      tags:
      - Verification
  /api/board/proof:
    get:
      operationId: getProofLog
      summary: FREE — append-only sha256 commitments over the archive
      description: Each day's published scores are committed to an append-only public log. Ships a verification recipe that reproduces byte-identically in Python and JavaScript. ?date=YYYY-MM-DD returns one commitment.
      parameters:
      - name: date
        in: query
        required: false
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Commitment log + recipe
      security: []
      tags:
      - Verification
  /api/board/signal-audit:
    get:
      summary: FREE — forward-return audit of our own published scores
      description: 'Marks every committed score to market: top-decile and entry-quality cohorts vs the board median AND a sector-matched ETF control, 1-day and 5-day forward. Methodology was frozen before the first result and we publish it even when it reads negative. Free, no payment or key — the point is that you can check our work before paying for it.'
      operationId: getSignalAudit
      responses:
        '200':
          description: Audit payload (or a 'computing' status before the next settle pass)
          content:
            application/json:
              schema:
                type: object
      security: []
      tags:
      - Verification
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.