> ## 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. # Newcomer whales > Wallets whose first known activity — the earlier of their first indexed fill and their first reconstructed position lifecycle — is within newcomerDays, and whose gross lifecycle notional over the last 90 days is at least minNotional. Wallets with no trade history whose first lifecycle sits on the lifecycle table's first day are excluded as window-start artefacts. ## OpenAPI ````yaml /api-reference/openapi.json get /api/public/v1/pulse/newcomer-whales 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/pulse/newcomer-whales: get: summary: Newcomer whales description: >- Wallets whose first known activity — the earlier of their first indexed fill and their first reconstructed position lifecycle — is within newcomerDays, and whose gross lifecycle notional over the last 90 days is at least minNotional. Wallets with no trade history whose first lifecycle sits on the lifecycle table's first day are excluded as window-start artefacts. operationId: list-api-public-v1-pulse-newcomer-whales parameters: - explode: false in: query name: newcomerDays schema: default: 30 format: int32 maximum: 90 minimum: 1 type: integer - explode: false in: query name: minNotional schema: default: 100000 format: double minimum: 0 type: number - explode: false in: query name: limit schema: default: 50 format: int32 maximum: 500 minimum: 1 type: integer - explode: false in: query name: offset schema: default: 0 format: int32 minimum: 0 type: integer responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/NewcomerWhale' type: - array - 'null' 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' '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: NewcomerWhale: additionalProperties: false properties: firstLifecycleAt: description: RFC3339 time the first reconstructed position lifecycle opened. type: string firstSeen: description: >- RFC3339. Earliest known activity: min(firstTradeAt, firstLifecycleAt). type: string firstTradeAt: description: >- RFC3339 time of the first indexed fill (trades table, back to 2025-02). null when the wallet has no trade history. type: - string - 'null' grossNotional: format: double type: number lifecycles: format: int32 type: integer totalPnl: format: double type: number wallet: type: string required: - wallet - firstSeen - firstTradeAt - firstLifecycleAt - grossNotional - totalPnl - lifecycles 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, or invalid_parameters. HTTP statuses and legacy code values remain unchanged. 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 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 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 ````