Coil Change Detection API

openapi: 3.2.0
info:
  title: Coil Agent Change Detection 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: Change Detection
  description: 'The polling loop: hash the board for free, buy the delta only when it moves. An unchanged hash is never billed.'
paths:
  /api/board/state:
    get:
      operationId: getBoardState
      summary: FREE — has the board materially changed?
      description: Returns a hash of the material state (each book's regime mode and ladder rung, plus the firing/ready candidate set) and nothing else. Poll it free and unlimited; buy a paid read only when the hash changes. Supports If-None-Match for a 304. Deliberately excludes the publish timestamp, which moves ~every 5 minutes without the state meaningfully changing. Also returns PER-BOOK hashes (books.spx, books.qqq, …) so an equities agent is not woken by a crypto change.
      parameters:
      - name: If-None-Match
        in: header
        required: false
        schema:
          type: string
        description: Your last state_hash, quoted. Returns 304 when unchanged.
      - name: syms
        in: query
        required: false
        schema:
          type: string
        example: NVDA,AMD
        description: Up to 25 tickers — returns a per-symbol hash so a watchlist agent polls only its own names.
      responses:
        '200':
          description: state_hash + freshness + where to buy when it moves
        '304':
          description: Unchanged since your last read
      security: []
      tags:
      - Change Detection
  /api/board/diff:
    get:
      operationId: getBoardDiff
      summary: What changed since the state hash you hold — poll free, buy only when it moves
      tags:
      - Change Detection
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.010000'
        protocols:
        - x402: {}
        - mpp:
            method: usdc
            intent: charge
            currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
        description: Buy the board diff — what changed since your last check (x402) — x402 'exact' charge, USDC on Base (eip155:8453). Amount in 6-decimal base units. Live offer in the endpoint's own 402 response.
        offers:
        - intent: charge
          method: x402
          amount: '10000'
          currency: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
          description: Buy the board diff — what changed since your last check (x402) — x402 'exact' charge, USDC on Base (eip155:8453). Amount in 6-decimal base units. Live offer in the endpoint's own 402 response.
        - intent: charge
          method: x402
          amount: '10000'
          currency: '31566704'
          description: Buy the board diff — what changed since your last check (x402) — x402 'exact' charge, USDCa on Algorand mainnet. Amount in 6-decimal base units. Live offer in the endpoint's own 402 response.
        - intent: charge
          method: x402
          amount: '10000'
          currency: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
          description: Buy the board diff — what changed since your last check (x402) — x402 'exact' charge, USDC on Solana mainnet. Amount in 6-decimal base units. Live offer in the endpoint's own 402 response.
        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 — x402 v2 payment requirements in the JSON body and the PAYMENT-REQUIRED header
        '200':
          description: 'The deltas between the hash you passed and the board right now: regime and permission-ladder moves per book, candidates entered/left the READY pool, and per-name trend, light, leadership and hold-band flips, with a deterministic one-line summary. Settlement receipt in the PAYMENT-RESPONSE header.'
          content:
            application/json:
              schema:
                type: object
          headers:
            X-Coil-Market-Open:
              schema:
                type: string
                enum:
                - 'true'
                - 'false'
              description: Whether the US equity market is open right now. When false the board will not change until the next session.
            X-Coil-Next-Refresh:
              schema:
                type: string
                format: date-time
              description: When the next board is expected. Do not re-buy before this time — you would receive an identical payload.
            X-Coil-Data-Age:
              schema:
                type: string
              description: Age of the served board in seconds.
        '400':
          description: 'Free, unbilled: ?since= missing, unknown or expired (no stored baseline to diff from). The body carries the current hash and the free /api/board/state endpoint to re-poll.'
      description: 'Change detection for polling agents. Pass ?since= the state_hash from a previous FREE /api/board/state poll and receive only the deltas: names that entered or left the READY candidate pool, per-name trend / light / leadership / hold-band flips, and any regime or permission-ladder move per book. The free hash tells you THAT the board moved; this tells you WHAT moved. Calling it with a hash equal to the current one is answered FREE with changed:false and is never billed; an unknown or expired hash also fails free with a 400. Baselines are stored for 7 days, written the first time a hash is observed.'
      parameters:
      - name: since
        in: query
        required: true
        schema:
          type: string
        description: The state_hash you stored from a previous GET /api/board/state (16 hex chars). Baselines are kept 7 days.
      - 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).'
      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.