> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xinsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Get Traders

> Returns trader intelligence for 1-25 wallet addresses or known usernames. Results preserve request order, duplicate inputs return duplicate rows, and each item is charged one batch item unit before execution. Unknown trader lookups return data with sync_status "unknown" matching the single trader endpoint.

Fetch up to 25 trader profiles in one call. Each item has the same shape as [Get Trader](/api-reference/endpoint/get-trader), plus a per-item `error` field when an address fails.

```bash theme={null}
curl -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"traders": ["0xabc...", "0xdef...", "swisstony"]}' \
  "https://api.0xinsider.com/api/v1/traders/batch"
```

Each item costs one unit against the batch budget: a 25-address batch reserves 25 units. The top-level status stays `200` even when some items fail, so check `data[i].error` per item. See [Rate Limits](/rate-limits).


## OpenAPI

````yaml POST /api/v1/traders/batch
openapi: 3.1.0
info:
  title: 0xinsider API
  description: >-
    Find your edge on Polymarket and Kalshi. Every wallet graded, every trade
    scored, every outlier flagged. API exposes trader grades, whale trades,
    smart money signals, and insider detection for AI agents, trading bots, and
    research tools. Normal API requests use a 30-second server timeout that
    returns HTTP 408 Request Timeout with an empty body when exceeded. Public
    REST /api/v1/* endpoints, excluding /api/v1/mcp, use Bearer-token based
    non-credentialed browser CORS: any Origin may call with Authorization,
    Content-Type, If-None-Match, Idempotency-Key, and Mcp-Session-Id request
    headers. Remote MCP at /api/v1/mcp is non-credentialed, but still validates
    Origin against the 0xinsider/localhost allowlist per MCP Streamable HTTP
    DNS-rebinding guidance. Successful browser CORS preflight responses
    advertise Access-Control-Max-Age: 86400. Browser JavaScript may read
    X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After,
    ETag, X-Request-Id, X-Request-Cost, X-Batch-RateLimit-Limit,
    X-Batch-RateLimit-Remaining, X-Batch-RateLimit-Reset, Mcp-Session-Id, and
    X-Mcp-Error-Code response headers. Credentialed first-party routes such as
    /api/keys, /api/billing, and auth endpoints remain restricted to configured
    0xinsider origins.
  version: 1.0.0
  contact:
    name: 0xinsider
    email: support@0xinsider.com
    url: https://0xinsider.com
servers:
  - url: https://api.0xinsider.com
    description: >-
      Production (live data). Authenticate with a live key (oxi_sk_live_...);
      requires an active Insider subscription.
  - url: https://api.0xinsider.com
    description: >-
      Sandbox / test mode (deterministic fixture data, no live rows).
      Authenticate with a test key (oxi_sk_test_...) on a free account. Same
      base URL and paths as production: the key class selects live vs sandbox.
      Test keys are billing-exempt, served from a fixed fixture dataset, and
      never read live data or persist writes; webhooks, usage, and MCP responses
      show the response shape only.
security:
  - bearerAuth: []
tags:
  - name: Traders
    description: Trader intelligence, batch lookups, timelines, and export readiness.
  - name: Positions
    description: Current prediction-market position snapshots from backend-owned mirrors.
  - name: Large Positions
    description: Largest current open positions from graded traders (Polymarket-only).
  - name: Whale Trades
    description: Recent and historical large trade intelligence.
  - name: Leaderboard
    description: Ranked trader discovery and category/strategy leaderboards.
  - name: Markets
    description: Market search, discovery, snapshots, and smart-score flow.
  - name: Insider Radar
    description: Suspicious trading pattern detection.
  - name: Events
    description: Durable public event replay streams.
  - name: Streaming
    description: Resumable real-time Server-Sent Events stream of live feed envelopes.
  - name: Webhooks
    description: Signed builder webhook destinations and delivery controls.
  - name: Usage
    description: Developer API budget and usage introspection.
  - name: System
    description: Health and operational status checks.
  - name: MCP
    description: Remote Model Context Protocol transport.
  - name: Reports
    description: Daily, weekly, monthly, and trader export report snapshots.
paths:
  /api/v1/traders/batch:
    post:
      tags:
        - Traders
      summary: Batch trader intelligence
      description: >-
        Returns trader intelligence for 1-25 wallet addresses or known
        usernames. Results preserve request order, duplicate inputs return
        duplicate rows, and each item is charged one batch item unit before
        execution. Unknown trader lookups return data with sync_status "unknown"
        matching the single trader endpoint.
      operationId: batchGetTraders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - traders
              properties:
                traders:
                  type: array
                  minItems: 1
                  maxItems: 25
                  items:
                    type: string
                expand:
                  type: array
                  items:
                    type: string
                    enum:
                      - strategy
                      - categories
                      - quant_metrics
                      - trust
                  description: Shared expand flags applied to every trader item.
            example:
              traders:
                - swisstony
                - '0x0000000000000000000000000000000000000000'
              expand:
                - strategy
      responses:
        '200':
          description: Ordered batch trader results
          headers:
            X-Request-Cost:
              schema:
                type: integer
              description: Number of batch item units charged for this request.
            X-Batch-RateLimit-Limit:
              schema:
                type: integer
              description: Batch item units allowed per minute.
            X-Batch-RateLimit-Remaining:
              schema:
                type: integer
              description: Batch item units remaining in the current sliding window.
            X-Batch-RateLimit-Reset:
              schema:
                type: integer
              description: Unix timestamp when the batch item window resets.
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                type: object
                required:
                  - object
                  - data
                  - meta
                properties:
                  object:
                    type: string
                    const: trader_batch
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BatchTraderItem'
                  meta:
                    $ref: '#/components/schemas/BatchResponseMeta'
              examples:
                success:
                  summary: Successful response
                  value:
                    object: traders
                    data: {}
                    meta:
                      request_id: req_example
                      cached: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/SubscriptionRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '408':
          $ref: '#/components/responses/RequestTimeout'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/RateLimitUnavailable'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl -sS \
              -X POST \
              -H 'Authorization: Bearer $OXI_SK' \
              -H 'Content-Type: application/json' \
              -d '{"traders":["swisstony","0x0000000000000000000000000000000000000000"],"expand":["strategy"]}' \
              'https://api.0xinsider.com/api/v1/traders/batch'
components:
  headers:
    X-RateLimit-Limit:
      description: Authenticated V1 per-user request limit for the current sliding window.
      schema:
        type: integer
        example: 100
    X-RateLimit-Remaining:
      description: >-
        Authenticated V1 requests remaining in the current sliding window after
        this response.
      schema:
        type: integer
        example: 84
    X-RateLimit-Reset:
      description: Unix timestamp when the authenticated V1 request window resets.
      schema:
        type: integer
        example: 1710772860
    X-Request-Id:
      description: Server-generated request identifier for support and tracing.
      schema:
        type: string
        example: req_550e8400
  schemas:
    BatchTraderItem:
      type: object
      required:
        - index
        - input
        - status
      properties:
        index:
          type: integer
          description: >-
            Zero-based request index. Duplicate inputs keep separate result
            rows.
        input:
          type: string
        status:
          type: string
          enum:
            - ok
            - error
        data:
          $ref: '#/components/schemas/Trader'
        error:
          $ref: '#/components/schemas/ApiErrorBody'
    BatchResponseMeta:
      type: object
      required:
        - request_id
        - cached
        - total_items
        - successful_items
        - failed_items
        - request_cost
        - rate_limit
      properties:
        request_id:
          type: string
        cached:
          type: boolean
        total_items:
          type: integer
        successful_items:
          type: integer
        failed_items:
          type: integer
        request_cost:
          type: integer
          description: Number of batch item units reserved before execution.
        rate_limit:
          $ref: '#/components/schemas/BatchRateLimitMeta'
    Trader:
      type: object
      required:
        - id
        - address
        - pnl
        - stats
      properties:
        id:
          type: string
          description: Prefixed ID (trd_...).
        address:
          type: string
        username:
          type: string
          nullable: true
        grade:
          type: string
          enum:
            - S
            - A
            - B
            - C
            - D
            - F
          nullable: true
        streak_tier:
          type: string
          enum:
            - hot
            - rising
            - neutral
            - cooling
            - cold
          nullable: true
          description: >-
            Hot-streak tier (trailing-7d cross-sectional percentile); a separate
            axis from the all-time grade. Null when no recent activity.
        score:
          type: number
          nullable: true
        rank:
          type: integer
          nullable: true
        pnl:
          type: object
          properties:
            total:
              type: number
              nullable: true
            realized:
              type: number
              nullable: true
            unrealized:
              type: number
              nullable: true
            last_7d:
              type: number
              nullable: true
            last_30d:
              type: number
              nullable: true
        stats:
          type: object
          properties:
            markets_traded:
              type: integer
              nullable: true
            win_rate:
              type: number
              nullable: true
            daily_win_rate:
              type: number
              nullable: true
            total_volume:
              type: number
              nullable: true
        strategy:
          type: object
          nullable: true
          properties:
            strategy_type:
              type: string
            description:
              type: string
              nullable: true
            confidence:
              type: number
              nullable: true
        category_strengths:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Per-category performance breakdown (expand=categories or
            expand[]=categories). Null unless expanded. Object keyed by category
            name; each value is the precomputed trader_rankings.category_ranks
            payload (rank, total_in_category, total_pnl, scaled_total_pnl,
            n_markets, wins, losses, win_rate; scaled_total_pnl is a legacy
            alias that currently equals total_pnl). Pass-through DB JSON: keys
            and value shape are DB-owned, so the inner shape is intentionally
            unconstrained and may carry additional compatibility fields.
        quant_metrics:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Advanced risk/performance metrics (expand=quant_metrics or
            expand[]=quant_metrics). Null unless expanded. Pass-through of the
            advanced_metrics row as JSON (trader_id and id stripped); the metric
            key-set is DB-owned and additive, so the inner shape is
            intentionally unconstrained.
        last_active:
          type: string
          format: date-time
          nullable: true
        synced_at:
          type: string
          format: date-time
          nullable: true
        sync_status:
          type: string
          nullable: true
          description: synced, unknown, or pending.
        trust:
          $ref: '#/components/schemas/TraderTrust'
          description: >-
            Field-level trust metadata. Present only when expand=trust or
            expand[]=trust is requested.
    ApiErrorBody:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        doc_url:
          type: string
          nullable: true
        param:
          type: string
          nullable: true
    BatchRateLimitMeta:
      type: object
      required:
        - basis
        - limit
        - remaining
        - reset
      properties:
        basis:
          type: string
          const: batch_items_per_minute
        limit:
          type: integer
        remaining:
          type: integer
        reset:
          type: integer
          description: Unix timestamp when the batch item window resets.
    ApiError:
      type: object
      required:
        - object
        - error
        - meta
      properties:
        object:
          type: string
          const: error
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - bad_request
                - invalid_api_key
                - subscription_required
                - forbidden
                - not_found
                - account_locked
                - rate_limited
                - rate_limit_unavailable
                - internal_error
            message:
              type: string
            doc_url:
              type: string
              nullable: true
            param:
              type: string
              nullable: true
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    TraderTrust:
      type: object
      description: >-
        Field-level trust metadata returned only when GET
        /api/v1/trader/{address} includes expand=trust.
      required:
        - total_pnl
        - realized_pnl
        - unrealized_pnl
        - markets_traded
        - win_rate
        - daily_win_rate
        - total_volume
        - grade
        - score
        - rank
        - streak_tier
        - strategy
        - category_strengths
        - quant_metrics
        - last_active
        - synced_at
        - sync_status
      properties:
        total_pnl:
          $ref: '#/components/schemas/TrustMetadata'
        realized_pnl:
          $ref: '#/components/schemas/TrustMetadata'
        unrealized_pnl:
          $ref: '#/components/schemas/TrustMetadata'
        markets_traded:
          $ref: '#/components/schemas/TrustMetadata'
        win_rate:
          $ref: '#/components/schemas/TrustMetadata'
        daily_win_rate:
          $ref: '#/components/schemas/TrustMetadata'
        total_volume:
          $ref: '#/components/schemas/TrustMetadata'
        grade:
          $ref: '#/components/schemas/TrustMetadata'
        score:
          $ref: '#/components/schemas/TrustMetadata'
        rank:
          $ref: '#/components/schemas/TrustMetadata'
        streak_tier:
          $ref: '#/components/schemas/TrustMetadata'
        strategy:
          $ref: '#/components/schemas/TrustMetadata'
        category_strengths:
          $ref: '#/components/schemas/TrustMetadata'
        quant_metrics:
          $ref: '#/components/schemas/TrustMetadata'
        last_active:
          $ref: '#/components/schemas/TrustMetadata'
        synced_at:
          $ref: '#/components/schemas/TrustMetadata'
        sync_status:
          $ref: '#/components/schemas/TrustMetadata'
    ResponseMeta:
      type: object
      required:
        - request_id
        - cached
      properties:
        request_id:
          type: string
          description: Unique request ID (req_ prefix).
        cached:
          type: boolean
        cache_age_s:
          type: integer
          nullable: true
          description: Cache age in seconds, null if not cached.
    TrustMetadata:
      type: object
      description: >-
        Shared source/freshness/reconciliation/completeness metadata for public
        API values that may be cached, stale, partial, computed, or
        provider-unavailable. Unavailable provider values must be represented
        with explicit metadata instead of fabricated zeros or empty arrays.
      required:
        - source
        - freshness
        - reconciliation
        - completeness
      properties:
        source:
          $ref: '#/components/schemas/TrustSource'
        freshness:
          $ref: '#/components/schemas/TrustFreshness'
        reconciliation:
          $ref: '#/components/schemas/TrustReconciliation'
        completeness:
          $ref: '#/components/schemas/TrustCompleteness'
    TrustSource:
      type: object
      description: >-
        Source metadata for a trust-critical value. Providers and DB/read models
        own business truth; clients should not infer missing provider facts from
        titles, slugs, zeros, or empty arrays.
      required:
        - kind
        - owner
      properties:
        kind:
          type: string
          enum:
            - provider
            - database
            - cache
            - computed
            - client_input
            - unavailable
        owner:
          type: string
          description: Provider, table/read-model, cache, or service that owns the value.
        field:
          type: string
          nullable: true
          description: Provider field, DB column, or computed field name when applicable.
    TrustFreshness:
      type: object
      description: >-
        Freshness metadata for a trust-critical value. This is separate from
        transport cache fields in ResponseMeta.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - fresh
            - refreshing
            - stale
            - not_live
            - unknown
            - unavailable
        as_of:
          type: string
          format: date-time
          nullable: true
        max_age_s:
          type: integer
          nullable: true
          minimum: 0
    TrustReconciliation:
      type: object
      description: How provider-owned facts were reconciled with stored/read-model values.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - provider_backed
            - db_mirror
            - computed
            - partial
            - not_applicable
            - unavailable
        detail:
          type: string
          nullable: true
    TrustCompleteness:
      type: object
      description: >-
        Whether the described value or result set is complete for its stated
        contract.
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - complete
            - partial
            - not_computed
            - not_applicable
            - unavailable
        detail:
          type: string
          nullable: true
  responses:
    BadRequest:
      description: Invalid request parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    SubscriptionRequired:
      description: Active Insider subscription required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: Account access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RequestTimeout:
      description: >-
        Request exceeded the server's 30-second transport timeout. The timeout
        response has an empty body because it is generated before handler-level
        JSON error shaping.
    Locked:
      description: Account is locked
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimited:
      description: >-
        Rate limit exceeded (100 req/min; batch endpoints also reserve 100 batch
        item units/min before execution)
      headers:
        Retry-After:
          description: Seconds until rate limit resets.
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
        X-Request-Id:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    RateLimitUnavailable:
      description: >-
        Redis-backed authenticated rate limiter unavailable; retry after the
        per-process outage cooldown
      headers:
        Retry-After:
          description: >-
            Seconds until the middleware will probe the Redis-backed rate
            limiter again.
          schema:
            type: integer
        X-Request-Id:
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key: Authorization: Bearer oxi_sk_live_... for live data (requires
        an active Insider subscription), or oxi_sk_test_... for sandbox/test
        mode (free account, deterministic fixture data, no live rows). Both key
        classes use the same paths; the prefix selects live vs sandbox.

````