> ## Documentation Index > Fetch the complete documentation index at: https://docs.coinversa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get API public v1 live whale trades by coin ## OpenAPI ````yaml /api-reference/openapi.json get /api/public/v1/live/whale-trades/{coin} openapi: 3.1.0 info: title: coinversa-api version: 0.1.0 servers: - url: https://api.coinversa.ai description: Production security: [] paths: /api/public/v1/live/whale-trades/{coin}: get: summary: Get API public v1 live whale trades by coin operationId: get-api-public-v1-live-whale-trades-by-coin parameters: - description: >- Market symbol, e.g. BTC or xyz:GOLD. Case and surrounding whitespace are normalized; the body echoes the canonical spelling. in: path name: coin required: true schema: description: >- Market symbol, e.g. BTC or xyz:GOLD. Case and surrounding whitespace are normalized; the body echoes the canonical spelling. type: string - description: >- Lookback window: digits followed by m, h or d (e.g. 30m, 6h). At least 1m (422 below) and at most 24h: the fills table has no index on notional, so cost grows with the coin's fill count in the window. Longer windows are rejected with 400, never silently narrowed. Equivalent spellings (6h, 360m) share one cache entry. explode: false in: query name: since schema: default: 6h description: >- Lookback window: digits followed by m, h or d (e.g. 30m, 6h). At least 1m (422 below) and at most 24h: the fills table has no index on notional, so cost grows with the coin's fill count in the window. Longer windows are rejected with 400, never silently narrowed. Equivalent spellings (6h, 360m) share one cache entry. pattern: ^[0-9]+[mhd]$ type: string - description: >- Smallest fill to return, USD notional (price x size). Default 1,000,000; the floor is 100,000; NaN and infinities are rejected. This is trade size, not the 'whale' size tier (lifetime volume). explode: false in: query name: minNotional schema: default: 1000000 description: >- Smallest fill to return, USD notional (price x size). Default 1,000,000; the floor is 100,000; NaN and infinities are rejected. This is trade size, not the 'whale' size tier (lifetime volume). format: double minimum: 100000 type: number - description: Largest fills to return, by notional. explode: false in: query name: limit schema: default: 50 description: Largest fills to return, by notional. format: int32 maximum: 200 minimum: 1 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/WhaleTradesBody' description: OK headers: X-Billing-Grace-Expires: $ref: '#/components/headers/X-Billing-Grace-Expires' X-Billing-State: $ref: '#/components/headers/X-Billing-State' X-RateLimit-Daily: $ref: '#/components/headers/X-RateLimit-Daily' X-RateLimit-Daily-Reset: $ref: '#/components/headers/X-RateLimit-Daily-Reset' X-RateLimit-Monthly: $ref: '#/components/headers/X-RateLimit-Monthly' X-RateLimit-Monthly-Reset: $ref: '#/components/headers/X-RateLimit-Monthly-Reset' X-RateLimit-Next: $ref: '#/components/headers/X-RateLimit-Next' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-RateLimit-Route: $ref: '#/components/headers/X-RateLimit-Route' X-RateLimit-Scope: $ref: '#/components/headers/X-RateLimit-Scope' X-RateLimit-Tier: $ref: '#/components/headers/X-RateLimit-Tier' X-Request-ID: $ref: '#/components/headers/X-Request-ID' '400': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Bad Request headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '403': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Forbidden headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '404': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Not Found headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '422': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Unprocessable Entity headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '429': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Too Many Requests headers: Retry-After: $ref: '#/components/headers/Retry-After' X-Billing-Grace-Expires: $ref: '#/components/headers/X-Billing-Grace-Expires' X-Billing-State: $ref: '#/components/headers/X-Billing-State' X-RateLimit-Daily: $ref: '#/components/headers/X-RateLimit-Daily' X-RateLimit-Daily-Reset: $ref: '#/components/headers/X-RateLimit-Daily-Reset' X-RateLimit-Monthly: $ref: '#/components/headers/X-RateLimit-Monthly' X-RateLimit-Monthly-Reset: $ref: '#/components/headers/X-RateLimit-Monthly-Reset' X-RateLimit-Next: $ref: '#/components/headers/X-RateLimit-Next' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-RateLimit-Route: $ref: '#/components/headers/X-RateLimit-Route' X-RateLimit-Scope: $ref: '#/components/headers/X-RateLimit-Scope' X-RateLimit-Tier: $ref: '#/components/headers/X-RateLimit-Tier' X-Request-ID: $ref: '#/components/headers/X-Request-ID' '500': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Internal Server Error headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' '504': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Gateway Timeout headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' security: - apiKey: [] components: schemas: WhaleTradesBody: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.coinversa.ai/schemas/WhaleTradesBody.json format: uri readOnly: true type: string aggressor: description: >- Always unknown: the fills table does not record which side took liquidity. type: string coin: description: Canonical market symbol. type: string count: description: Fills returned (len(trades)). format: int64 type: integer coverage: $ref: '#/components/schemas/WhaleTradesCoverage' minNotional: description: Notional floor applied, USD. format: double type: number notes: items: type: string type: - array - 'null' ranking: description: Always notional_desc. type: string since: description: Window as requested. type: string source: $ref: '#/components/schemas/WhaleTradesSource' tierAssignment: description: >- Always current: cohorts are the wallets' tiers now, not at fill time. type: string trades: description: Largest notional first, then newest first. items: $ref: '#/components/schemas/WhaleTrade' type: - array - 'null' truncated: description: >- True when at least one more fill above minNotional exists in the window beyond the returned limit (the query fetches limit + 1). type: boolean windowEnd: description: >- Exclusive end of the window, Unix ms UTC — captured once before querying. format: int64 type: integer windowStart: description: >- Inclusive start of the window, Unix ms UTC — the exact bound passed to SQL. format: int64 type: integer required: - coin - since - minNotional - windowStart - windowEnd - ranking - tierAssignment - aggressor - count - truncated - trades - source - coverage - notes type: object APIError: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.coinversa.ai/schemas/APIError.json format: uri readOnly: true type: string code: description: Machine-readable error code; retained for compatibility. type: string current_tier: description: Caller's effective tier type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string reason: description: >- More specific recovery reason when available: missing_api_key, invalid_api_key, insufficient_tier, invalid_parameters, or account_suspended. Account suspensions return 403 with code ACCOUNT_SUSPENDED; contact support rather than retrying or upgrading. type: string required_tier: description: Minimum tier for this operation type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upgrade_url: description: Where to upgrade type: string type: object WhaleTradesCoverage: additionalProperties: false properties: completeness: description: >- Always 'unknown' until the syncer provides an ingestion watermark: fills still in flight at compute time are missing without notice. type: string required: - completeness type: object WhaleTradesSource: additionalProperties: false properties: asOf: description: >- When this body was computed, Unix ms. Preserved on cache hits (refreshes every 60 s). This is compute time, not an ingestion watermark. format: int64 type: integer cadence: type: string kind: description: 'Always ''fills'': individual matches, not aggregated volume.' type: string observedThrough: description: >- Ingestion watermark (how far the fill stream had been indexed), Unix ms. Always null today: the syncer exposes none, so the last minutes of the window may be incomplete. format: int64 type: - integer - 'null' table: description: 'Always trades: indexed Hyperliquid fills.' type: string required: - table - kind - asOf - observedThrough - cadence type: object WhaleTrade: additionalProperties: false properties: buyer: $ref: '#/components/schemas/WhaleTradeParty' description: The side that bought (side B). idKind: description: >- exchange: one fill, both counterparties can be paired. synthetic: one wallet's observation of a fill whose exchange id was missing; its counterparty cannot be paired and may appear as a separate row. type: string notional: description: price x size, USD. format: double type: number price: description: Fill price, USD per unit. format: double type: number seller: $ref: '#/components/schemas/WhaleTradeParty' description: The side that sold (side A). size: description: Fill size, base units. format: double type: number tid: description: >- Trade id as a decimal string (64-bit; do not parse into a JavaScript number). Positive: Hyperliquid's exchange id, shared by both counterparties. Negative: a syncer-generated, wallet-specific synthetic id (idKind synthetic). type: string time: description: >- Fill time, Unix ms (UTC; independent of the database session time zone). format: int64 type: integer required: - tid - idKind - time - price - size - notional - buyer - seller type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object WhaleTradeParty: additionalProperties: false properties: address: description: >- Wallet address, 0x-prefixed hex; empty when the counterparty is not an indexed wallet. type: string direction: description: >- What the fill did to this wallet's position: Open Long, Close Short, Long > Short, ...; empty when unknown. type: string pnlTier: description: >- Wallet's CURRENT all-time PnL tier (legacy slug); empty when unknown. type: string sizeTier: description: >- Wallet's CURRENT lifetime-volume tier (legacy slug); empty when unknown. type: string required: - address - pnlTier - sizeTier - direction type: object headers: X-Billing-Grace-Expires: description: RFC3339 time when billing grace expires, when applicable. schema: type: string X-Billing-State: description: Billing grace state, when applicable. schema: type: string X-RateLimit-Daily: description: >- Daily account allowance reported by the existing counter check, clamped at zero. Best-effort; present only for a capped tier that reaches the quota check. schema: type: string X-RateLimit-Daily-Reset: description: >- Unix seconds (UTC) after the selected daily quota bucket expires. Not a source-data timestamp. schema: type: string X-RateLimit-Monthly: description: >- Monthly account allowance reported by the existing counter check, clamped at zero. Best-effort; present only for a capped tier that reaches the quota check. schema: type: string X-RateLimit-Monthly-Reset: description: >- Unix seconds (UTC) after the selected monthly quota bucket expires. Follows the existing billing anchor. schema: type: string X-RateLimit-Next: description: >- Legacy Go duration string until the next token is available across the checked buckets; not the daily/monthly reset. schema: type: string X-RateLimit-Remaining: description: >- Minimum remaining tokens across the checked minute and per-route token buckets (account for keys, IP for anonymous requests). Not a fixed-window request allowance. schema: type: string X-RateLimit-Reset: description: >- Unix seconds (UTC), rounded up, when the checked token buckets next permit a request, assuming no competing traffic. Not a full bucket refill. schema: type: string X-RateLimit-Route: description: Remaining tokens in the account's per-route token bucket. schema: type: string X-RateLimit-Scope: description: >- account for authenticated requests (shared across keys); ip for anonymous requests. Describes the limiter scope, not the key's resolved tier. schema: type: string X-RateLimit-Tier: description: Effective tier for this request; only present after access checks pass. schema: type: string X-Request-ID: description: >- Server-generated correlation ID. Include it in a support report; not a guarantee that an unauthenticated request appears in account usage logs. schema: type: string Retry-After: description: >- On HTTP 429, whole seconds to wait before retrying, rounded up. Other traffic may still consume the available allowance. schema: type: string securitySchemes: apiKey: description: >- Create an API key at https://developers.coinversa.ai/keys. REST limits are shared across keys by account; access uses the effective tier of the presented key. in: header name: X-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.