> ## 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.

# Remote MCP

> Model Context Protocol (MCP) Streamable HTTP transport. Accepts a JSON-RPC 2.0 request and returns a JSON-RPC response. Supported methods: initialize, notifications/initialized, ping, tools/list, tools/call. Remote MCP exposes 29 read-only tools for public V1 read operations: get_leaderboard, get_trader, batch_get_traders, get_whale_trades, get_whale_trade, get_whale_trades_history, get_market_intel, batch_get_market_intel, get_smart_money_flows, get_market_snapshot, get_insider_radar, get_insider_radar_flag, get_positions, get_position_timeline, get_position_timeline_by_id, search_markets, explore_markets, get_event_replay_since, list_webhooks, get_webhook, get_daily_report_snapshot, get_weekly_report_snapshot, get_monthly_report_snapshot, get_report, get_trader_export_snapshot, get_platforms, get_large_positions, get_trending_wallets, get_trader_pnl. Webhook create/update/delete/verify/rotate operations are intentionally not exposed as remote MCP tools. The remote endpoint advertises tools only; it does not implement resources/list, resources/read, prompts/list, or prompts/get. Each tool dispatches to the matching /api/v1/* handler in-process so auth, rate limits, and payload shape match. Auth should use Authorization: Bearer <token>. ?token=<token> remains a legacy compatibility path for URL-only MCP clients, but URL secrets can land in shell history, browser history, and logs, so prefer headers or the stdio package. Mcp-Session-Id is minted on initialize and echoed on every response. Origin header, when present, is validated against the 0xinsider + localhost allowlist.

Hosted, streamable HTTP MCP endpoint. Use it when your agent can't spawn a local `npx` subprocess: a serverless function, a browser-based agent, or a hosted automation runtime.

Remote MCP exposes the 21 read-only V1 data operations below as tools. Each tool dispatches to the matching `/api/v1/*` handler in-process, so auth, rate limits, and payload contracts match direct REST calls. Meta endpoints (`/usage`, `/health`) and webhook mutations are not exposed as tools.

The remote endpoint is tools-only. It supports `initialize`, `notifications/initialized`, `ping`, `tools/list`, and `tools/call`; it does not implement resources or prompts.

Current tools:

* `get_leaderboard`
* `get_trader`
* `batch_get_traders`
* `get_whale_trades`
* `get_whale_trades_history`
* `get_market_intel`
* `batch_get_market_intel`
* `get_market_snapshot`
* `get_insider_radar`
* `get_positions`
* `get_position_timeline`
* `get_position_timeline_by_id`
* `search_markets`
* `explore_markets`
* `get_event_replay_since`
* `list_webhooks`
* `get_webhook`
* `get_daily_report_snapshot`
* `get_weekly_report_snapshot`
* `get_monthly_report_snapshot`
* `get_trader_export_snapshot`

## Authentication

Prefer the header form:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer $OXINSIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' \
  https://api.0xinsider.com/api/v1/mcp
```

A `?token=...` query parameter is still available for URL-only clients but is **legacy**. URL secrets leak into shell history, browser history, proxies, and logs. Use headers wherever you can.

For the streaming response, see [Remote MCP Stream](/api-reference/endpoint/remote-mcp-stream).


## OpenAPI

````yaml POST /api/v1/mcp
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/mcp:
    post:
      tags:
        - MCP
      summary: Remote MCP endpoint (JSON-RPC)
      description: >-
        Model Context Protocol (MCP) Streamable HTTP transport. Accepts a
        JSON-RPC 2.0 request and returns a JSON-RPC response. Supported methods:
        initialize, notifications/initialized, ping, tools/list, tools/call.
        Remote MCP exposes 29 read-only tools for public V1 read operations:
        get_leaderboard, get_trader, batch_get_traders, get_whale_trades,
        get_whale_trade, get_whale_trades_history, get_market_intel,
        batch_get_market_intel, get_smart_money_flows, get_market_snapshot,
        get_insider_radar, get_insider_radar_flag, get_positions,
        get_position_timeline, get_position_timeline_by_id, search_markets,
        explore_markets, get_event_replay_since, list_webhooks, get_webhook,
        get_daily_report_snapshot, get_weekly_report_snapshot,
        get_monthly_report_snapshot, get_report, get_trader_export_snapshot,
        get_platforms, get_large_positions, get_trending_wallets,
        get_trader_pnl. Webhook create/update/delete/verify/rotate operations
        are intentionally not exposed as remote MCP tools. The remote endpoint
        advertises tools only; it does not implement resources/list,
        resources/read, prompts/list, or prompts/get. Each tool dispatches to
        the matching /api/v1/* handler in-process so auth, rate limits, and
        payload shape match. Auth should use Authorization: Bearer <token>.
        ?token=<token> remains a legacy compatibility path for URL-only MCP
        clients, but URL secrets can land in shell history, browser history, and
        logs, so prefer headers or the stdio package. Mcp-Session-Id is minted
        on initialize and echoed on every response. Origin header, when present,
        is validated against the 0xinsider + localhost allowlist.
      operationId: createMcpJsonRpcResponse
      parameters:
        - name: token
          in: query
          required: false
          description: >-
            Deprecated compatibility API-key query parameter for remote MCP
            clients that cannot send Authorization headers. Prefer
            Authorization: Bearer <token> or the stdio package because URL
            secrets are easier to leak through logs and history.
          schema:
            type: string
        - name: Mcp-Session-Id
          in: header
          required: false
          description: >-
            Session ID minted by the server on initialize; echoed on every
            subsequent request.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - jsonrpc
                - method
              properties:
                jsonrpc:
                  type: string
                  const: '2.0'
                id:
                  oneOf:
                    - type: string
                    - type: number
                    - type: 'null'
                method:
                  type: string
                  enum:
                    - initialize
                    - notifications/initialized
                    - ping
                    - tools/list
                    - tools/call
                params:
                  type: object
            example: {}
      responses:
        '200':
          description: JSON-RPC response
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonrpc
                  - id
                properties:
                  jsonrpc:
                    type: string
                    const: '2.0'
                  id:
                    oneOf:
                      - type: string
                      - type: number
                      - type: 'null'
                  result:
                    type: object
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: integer
                      message:
                        type: string
              examples:
                success:
                  summary: Successful response
                  value:
                    object: mcp
                    data: {}
                    meta:
                      request_id: req_example
                      cached: false
          headers:
            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'
        '202':
          description: Notification acknowledged (no body)
          headers:
            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'
        '400':
          description: JSON-RPC parse or invalid-request error
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/SubscriptionRequired'
        '403':
          description: Origin rejected or tier forbidden
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl -sS \
              -X POST \
              -H 'Authorization: Bearer $OXI_SK' \
              -H 'Content-Type: application/json' \
              -d '{}' \
              'https://api.0xinsider.com/api/v1/mcp'
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
  responses:
    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'
    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'
  schemas:
    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'
    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.
  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.

````