Chord Token safety API

openapi: 3.2.0
info:
  title: Chord Token safety API
  version: '2026-10-05'
  summary: Trade, data and agent endpoints for eight EVM chains (Ethereum 1, Arbitrum One 42161, Base 8453, BNB Chain 56, Avalanche 43114, Monad 143, Arc 5042, Robinhood Chain 4663) and Solana (data and swaps).
  description: 'Chord is a non-custodial trading app and on-chain data index. The API has three kinds of endpoint:


    - **Trade**: `/quote` finds the best route across every venue on the chain; `/swap` turns it into a transaction you sign yourself. Chord never holds funds or keys.

    - **Read**: every swap on the chain, rolled up by token, venue and hour, from Chord''s own index — tokens, launches, holders, top wallets, portfolio PnL, liquidity positions and pools. No key needed. Avalanche, Base, BNB Chain, Arbitrum One and Ethereum have the same rollups under `/chains/{chain}/*`; Solana has its own data family under `/chains/solana/*` (base58 addresses, case-sensitive) and its swaps under `/sol/trade/*`.

    - **Agent**: the analyst (`/ask`) and the streams.


    Amounts are decimal strings in the token''s smallest unit. Timestamps are Unix seconds unless the field is `updatedAt` (milliseconds). `GET /portfolio/{wallet}` and `/portfolio/{wallet}/activity` differ on both: amounts there are in whole tokens and every time is in milliseconds. Reads answer anonymous callers at 60 requests a minute per IP; an `X-API-Key` header raises that to your plan. Every non-2xx body is `{ error, message }`.'
  contact:
    name: Chord
    url: https://getchord.xyz/developer
  x-logo:
    url: https://getchord.xyz/chord/pwa-192x192.png?v=20261019
servers:
- url: https://api.getchord.xyz/v1
  description: Production
tags:
- name: Token safety
  description: 'Chord''s safety report for one token on its eight EVM chains or Solana: its own contract scan and buy-then-sell simulation, GoPlus (Powered by Go+ Security), Sourcify, RugCheck and Chord''s tape, one verdict decided in code.'
paths:
  /security/token/{chain}/{address}:
    get:
      tags:
      - Token safety
      operationId: getTokenSecurity
      summary: Is a token safe
      description: 'Chord''s safety report for one token: the same report the Ask analyst, the trade dock and the trade card read.


        **What runs**: on the EVM chains, Chord''s own contract scan (proxy wiring and who can upgrade it, the owner and what the owner can do: mint, block wallets, pause, change taxes or limits), a $20 buy and its sell back through Chord''s router simulated as a test wallet (nothing is sent), the transfer-tax probe, GoPlus, Sourcify and Chord''s own tape screen (wash trading, buyer clusters, rugs, buyers who cannot sell, a copied ticker). On Solana: RugCheck, GoPlus, Jupiter and the screen of Chord''s Solana tape (mint and freeze authority, Token-2022 extensions, LP lock, holders, the creator''s history). A source that does not answer leaves its checks `unknown` and the report `partial`; it is never read as a pass.


        **Use it for**: "is this token safe to buy", a rug or honeypot check before a trade, an agent''s pre-trade gate (refuse `avoid`, warn on `caution`).


        **Notes**

        - Cached 10 minutes (2 to 3 minutes when a source did not answer, seconds when nothing could test selling an unvetted token or the check was cut short on Chord''s side; such a partial report is sent `Cache-Control: private, max-age=10`). A report built cold on an EVM chain can take up to about 20 seconds. An address with no contract answers 404 at once.

        - A report already cached answers anyone. Without an API key (or an Ask session), one IP builds at most 10 new reports every 10 minutes, and every such caller together a limited number a minute; past either the answer is 429 or 503 `BUSY` with `Retry-After`, and nothing is checked. Send an `X-API-Key` for more.

        - `verdict` is decided in code from `checks`. No verdict rests on GoPlus alone: when only GoPlus answered, the report is `partial` and says Chord''s own checks did not run. A reading from GoPlus names it "GoPlus (Powered by Go+ Security)".

        - A Solana mint is used exactly as given (base58 is case-sensitive).'
      parameters:
      - name: chain
        in: path
        required: true
        schema:
          type: string
        description: 'Chain id or name: `1` / `ethereum`, `56` / `bnb`, `143` / `monad`, `4663` / `robinhood`, `5042` / `arc`, `8453` / `base`, `42161` / `arbitrum`, `43114` / `avalanche`, or `solana`.'
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: The token contract (0x followed by 40 hex characters), or the Solana mint exactly as written (base58, 32 bytes).
      responses:
        '200':
          description: The report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenRiskReport'
        '400':
          description: '`UNSUPPORTED_CHAIN` (a chain Chord does not check, or one not served yet) or `INVALID_ADDRESS`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`NOT_A_CONTRACT`: the chain answered and there is no contract at this address. `NOT_A_MINT`: no Solana source knows this address as a token.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`RATE_LIMITED`: without an API key, this IP built its 10 new reports of the last 10 minutes (`Retry-After`); cached reports still answer. Or `RATE_LIMIT_EXCEEDED`, the per-minute limit of every route.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: '`BUSY`: too many new reports are being built for callers without a key right now (`Retry-After`). `UNAVAILABLE`: the check could not run just now. Retry; do not treat either as a clean result.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Stable machine code, e.g. `INVALID_PARAMS`, `NOT_READY`, `RATE_LIMIT_EXCEEDED`.
        message:
          type: string
          description: For humans.
        statusCode:
          type: integer
          description: HTTP status, when included.
      description: Every non-2xx body.
      required:
      - error
      example:
        error: INVALID_PARAMS
        message: amount must be an integer string in the token's smallest unit
    TokenRiskReport:
      type: object
      properties:
        chain:
          oneOf:
          - type: integer
          - type: string
            const: solana
          description: The chain id, or `solana`.
        address:
          type: string
          description: The token (0x, lower-cased) or the Solana mint (case kept).
        symbol:
          type:
          - string
          - 'null'
          description: 'As the contract or the token list names it: chosen by whoever launched the token.'
        name:
          type:
          - string
          - 'null'
          description: ''
        verdict:
          type: string
          enum:
          - avoid
          - caution
          - ok
          - unknown
          description: 'Decided in code from the checks, never by a model. `avoid`: it cannot be sold, a sell tax of 30% or more, a scam verdict of Chord''s tape screen, or a copy of a listed token''s ticker. `caution`: a check that warns (taxes of 5 to 30%, an owner who can mint, block wallets or pause, code one wallet can upgrade, unverified source, unlocked liquidity one provider can pull, top 10 holders over 60% …). `ok`: none of that, with two independent sources answering and a sell test passing. `unknown`: too few sources, or nothing could test selling it. Never read `ok` as a guarantee.'
        score:
          type:
          - integer
          - 'null'
          description: 0 (worst) to 100, in the verdict's band; null when the verdict is `unknown`.
        checks:
          type: array
          items:
            $ref: '#/components/schemas/RiskCheck'
          description: Every check, in a fixed order.
        facts:
          type: object
          additionalProperties: true
          description: 'The numbers behind the checks: `buyTaxPct`, `sellTaxPct`, `transferTaxPct`, `honeypot`, `owner`, `ownerRenounced`, `proxy`, `implementation`, `upgrader`, `verifiedSource`, `mintable`, `blacklist`, `pausable`, `lpLockedPct`, `top10Pct`, `holders`, `creator`, `creatorPct`, `screenLevel`, `screenReasons`, `simulation` (Chord''s $20 buy and sell back: status, taxes, round trip), `reasons` (the counted reasons, worst first), `answered` / `missing` (the sources), `goplusOnly` (only GoPlus answered: the report is partial). Solana adds `mintAuthority`, `freezeAuthority`, `token2022Extensions`, `permanentDelegate`, `liquidityUsd`, `pools`, `topHolders`, `jupiterVerified`, `rugcheckScore` …'
        sources:
          type: array
          items:
            type: object
            properties:
              label:
                type: string
                description: ''
              href:
                type: string
                description: ''
          description: Where to read it yourself (explorer, GoPlus, RugCheck, Sourcify, Jupiter).
        checkedAt:
          type: integer
          description: Unix time, milliseconds — when the server built this answer.
        partial:
          type: boolean
          description: True when at least one source did not answer, or when GoPlus was the only one that did.
        vetted:
          type: boolean
          description: 'On a list Chord trusts (stock / ETF / bridged list token, the bridge provider''s list, Monad''s verified list, a registry anchor; on Solana Jupiter-verified majors): the issuer''s own powers (mint, freeze, pause, upgrades) are listed but do not raise the verdict. Taxes and the sell test still count.'
      description: Chord's safety report for one token.
      required:
      - chain
      - address
      - verdict
      - score
      - checks
      - facts
      - sources
      - checkedAt
      - partial
      - vetted
    RiskCheck:
      type: object
      properties:
        id:
          type: string
          description: 'Stable id, snake_case: `honeypot`, `buy_tax`, `sell_tax`, `transfer_tax`, `round_trip`, `owner_can_mint`, `blacklist`, `pausable`, `owner_privileges`, `hidden_owner`, `proxy_upgradeable`, `unverified_source`, `lp_unlocked`, `top10_holders`, `creator_holds`, `creator_history`, `tape_screen`, `impostor_ticker`, `own_checks` …; Solana adds `freeze_authority`, `mint_authority`, `token2022_extensions`, `mutable_metadata`, `liquidity` …'
        label:
          type: string
          description: Short English label (`Sell tax`, `Owner can mint`).
        status:
          type: string
          enum:
          - pass
          - warn
          - fail
          - unknown
          description: '`unknown` = the source that reads it did not answer, or nothing could test it. Never `pass` for a check that did not run.'
        detail:
          type: string
          description: One sentence with the measured number (`Selling loses 40% to the token's own tax (Chord simulation 40%, GoPlus 40%).`).
        source:
          type: string
          description: Who read it, in words, at most 60 characters (`Chord simulation`, `Chord contract scan`, `Chord tape`, `RugCheck`, `Sourcify`). A reading from GoPlus says `GoPlus (Powered by Go+ Security)`.
      description: One check of the report.
      required:
      - id
      - label
      - status
      - detail
      - source
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Optional on every read. A key from getchord.xyz/developer raises the rate limit to your plan and meters usage per key. Required for `?only=` on quotes and for the Ask agent API.
    Session:
      type: http
      scheme: bearer
      description: A Google sign-in session minted by the app (`nts_…`). Only the browser surfaces use it; agents use `ApiKey`.