Coil Coil Live API

openapi: 3.2.0
info:
  title: Coil Agent Coil Live 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: Coil Live
  description: 'Subscription lane ($49/mo): the engine-grade feed and the served, versioned trading discipline. License key, never sold per call.'
paths:
  /api/live/feed:
    get:
      summary: Coil Live — the engine-grade board feed
      description: 'The feed the live record trades, served to your agent: per-name structural stops, targets, conviction, lanes, plus a served candidates[] entry pool (a read-time join of READY picks and day-board grades — an empty list means the discipline is working, not an outage). Refreshed about every 5 minutes in market hours. Payload carries field_notes, timestamps_note and freshness.is_stale so an agent never has to guess at the vocabulary or do clock math. Subscription only — never sold per-call over x402. Engine fields include coil_score / coil_kind (compression or held post-catalyst) since 2026-09-03.'
      operationId: getLiveFeed
      tags:
      - Coil Live
      security:
      - licenseKey: []
      parameters:
      - name: symbols
        in: query
        required: false
        schema:
          type: string
          example: NVDA,MU
        description: 'Comma-separated tickers for a small poll read. candidates[] always rides whole regardless. Measured: unfiltered the payload is about 1.35 MB and a two-name read about 70 KB — never read the unfiltered feed into a model context; add compact=true (about 12 KB for two names).'
      - name: compact
        in: query
        required: false
        schema:
          type: boolean
        description: 'Optional, default false (the full payload, unchanged). true = core fields only: names and engine_fields keep the core keys; schema, rotation, awareness, perf, pair_rotation, book detail beyond regime, and day rows/cohorts are dropped. candidates[], freshness and rules_version always ride.'
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: 'Optional: comma-separated engine_fields keys to keep per name (e.g. stop,target,rr). Unknown keys are echoed in unknown_fields.'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
        description: 'Optional: page size, names per page, sorted by symbol (1-1000). The response carries page.next_cursor.'
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: 'Optional: the page.next_cursor from the previous page (the last symbol returned). Omit for the first page.'
      responses:
        '200':
          description: The engine-grade feed.
          content:
            application/json:
              schema:
                type: object
        '401':
          description: 'No or invalid license key. Body: {"error":"subscription_required","note":"Coil Live ($49/mo or $419/yr) — subscribe at https://coil.trade/live-feed, then send the license as X-License-Key."}'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: subscription_required
                  note:
                    type: string
  /api/live/setup:
    get:
      summary: Coil Live — how to connect (free, no key)
      description: 'Unauthenticated discovery: returns the product name, price, checkout URL and the exact header/MCP instructions for connecting an agent. Call this first.'
      operationId: getLiveSetup
      tags:
      - Coil Live
      responses:
        '200':
          description: Connection instructions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    type: string
                    example: coil-live
                  price:
                    type: string
                    example: $49/mo or $419/yr
                  checkout:
                    type: string
                    example: https://coil.trade/live-feed
                  how:
                    type: string
                  docs:
                    type: string
                    example: https://coil.trade/agents
      security: []
  /api/live/rules:
    get:
      operationId: getLiveRules
      summary: Coil Live — the served trading discipline (versioned rulebook)
      description: 'The versioned rulebook a subscriber''s agent runs against /api/live/feed: cycle order, exits-first, the four entry guards (gap-down / broken-read / chase / day-low chase), the 3% max-loss stop, the losing-streak sizing rule, sizing precedence with the PDT bound, and fail-closed staleness. The response carries rules_version and a changelog; agents finish open positions under the version they were opened under and adopt new versions for new entries. Also served over MCP as the get_live_rules tool. Requires an active Coil Live subscription (X-License-Key).'
      security:
      - licenseKey: []
      responses:
        '200':
          description: The served discipline
          content:
            application/json:
              schema:
                type: object
                properties:
                  product:
                    type: string
                    example: coil-live-rules
                  rules_version:
                    type: string
                    example: 1.3.0
                  changelog:
                    type: array
                    items:
                      type: object
                      properties:
                        version:
                          type: string
                        date:
                          type: string
                        note:
                          type: string
                  rules:
                    type: string
                    description: The full rulebook, markdown
                required:
                - rules_version
                - rules
        '401':
          description: 'No or invalid license key. Body: {"error":"subscription_required","note":"Coil Live ($49/mo or $419/yr) — subscribe at https://coil.trade/live-feed, then send the license as X-License-Key."}'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: subscription_required
                  note:
                    type: string
        '403':
          description: invalid_license
      tags:
      - Coil Live
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.