openapi-sandbox.yaml

openapi: 3.1.0
info:
  title: OnChainRisk Sandbox API
  version: 1.0.0
  license:
    name: Proprietary
    url: https://onchainrisk.io/terms
  description: |
    **[⬇ Download OpenAPI spec (YAML)](/openapi-sandbox.yaml)** — for codegen tools (openapi-generator, orval, etc.)

    ---

    Sandbox tier for developers to evaluate OnChainRisk integration with real
    addresses and real responses, without the compute cost of a full paid
    analysis.

    ## What Sandbox is for

    - Auth testing - confirm your API key works
    - Response envelope validation - see actual field types and shapes
    - Integration testing - wire your client against a real endpoint
    - Basic UI prototyping

    ## What Sandbox is NOT for

    - Production monitoring or alerting bots
    - Large-scale tracing or attribution
    - Any workflow that depends on historical data beyond 7 days
    - Graph expansion, cluster analysis, cross-chain tracing

    ## Authentication

    Create a sandbox API key in the dashboard at
    https://app.onchainrisk.io/dashboard/api-keys. Free-tier accounts can create
    a sandbox key. Key management (create, list, revoke) is dashboard-only
    and intentionally not exposed here.

    Send your key in the `Authorization` header:

        Authorization: Bearer ocr_test_...

    New sandbox keys minted by the dashboard use the `ocr_test_*` prefix.
    Sandbox keys created before the prefix split remain valid and may
    appear with the legacy `ocr_live_*` prefix; either form authenticates
    as a sandbox key based on the underlying key tier.

    ## Rate Limits

    Token bucket algorithm.

    | Scope   | Capacity | Refill       |
    |---------|----------|--------------|
    | Per key | 20       | 10 per min   |
    | Per IP  | 30       | 30 per min   |

    429 responses include a `Retry-After` header and a body with `bucket`
    and `retry_after_seconds`.

    ## Response Policy

    Sandbox responses keep the same core envelope as paid (`address`,
    `network`, `riskScore`, `riskLevel`, `addressInfo`, `_sandbox`, etc.),
    but many expensive fields are gated:

    - gated objects are returned as `null` (e.g. `tokenFlow`, `clusters`, `honeypot`)
    - gated arrays are returned as `[]` (e.g. `topCounterparties`, `addressConnections`)
    - gated scalars are omitted entirely (e.g. `analysisMode`, `fullAnalysisAvailable`)
    - truncated arrays keep only recent items (e.g. `transactionHistory` = last 7 days)

    The authoritative list for a given response lives in `_sandbox.gated_fields[]`
    and `_sandbox.truncated_fields{}`. Clients should treat these as source of
    truth and NOT assume every paid field will be present.

    ## Sandbox signal (canonical)

    A client can detect sandbox mode two ways:

    1. Response contains a `_sandbox` root object with `profile: "sandbox"`
    2. `GET /api/user/me` returns `key_type: "sandbox"` and `api_mode: "sandbox"`

    No other fields are overloaded with sandbox semantics - `plan`, `riskLevel`,
    `riskConfidence`, `dataQuality` and other enums keep their existing paid
    value vocabularies.

    ## Validation errors

    Address validation runs before any blockchain scan. On failure the API
    returns **HTTP 422** with this envelope:

    ```json
    {
      "success": false,
      "error": {
        "message": "Validation failed",
        "code": "VALIDATION_ERROR",
        "details": {
          "address": "Address format does not match selected network. The address looks like a tron address, but network was set to eth.",
          "errorCode": "ADDRESS_NETWORK_MISMATCH",
          "detectedFamily": "tron",
          "requestedNetwork": "eth"
        }
      }
    }
    ```

    `error.code` is always `VALIDATION_ERROR` for this class. The granular
    reason lives in `error.details.errorCode`:

    | `errorCode`                   | When                                                                             |
    |-------------------------------|----------------------------------------------------------------------------------|
    | `INVALID_ADDRESS`             | empty, wrong format, whitespace-only                                             |
    | `UNSUPPORTED_NETWORK`         | `network` not in the supported list                                              |
    | `COULD_NOT_DETECT_NETWORK`    | address format unrecognised AND `network` omitted                                |
    | `INVALID_ADDRESS_CHECKSUM`    | decode succeeded, family checksum failed (Tron / BTC-legacy / LTC-legacy). Solana decode failures surface as `INVALID_ADDRESS` because Solana is not checksum-based. |
    | `ADDRESS_NETWORK_MISMATCH`    | detected address family inconsistent with requested `network`                    |

    `detectedFamily` and `requestedNetwork` are present only when they add
    useful diagnostic context; both may be `null` or absent.
  contact:
    name: OnChainRisk Support
    url: https://app.onchainrisk.io/dashboard/support
    email: admin@onchainrisk.io

servers:
  - url: https://api.onchainrisk.io
    description: Production (sandbox requests use the same host)

tags:
  - name: Analysis
    description: Address risk analysis (sandbox profile)
  - name: Graph
    description: |
      Transaction graph preview (sandbox profile). Limited to depth 1,
      last 7 days, capped nodes/edges. Upgrade for full historical graph
      expansion via paid `/api/graph/expand`.
  - name: Account
    description: Current user profile and usage

security:
  - ApiKeyAuth: []

paths:
  /api/v1/check:
    post:
      operationId: sandboxCheckAddress
      tags: [Analysis]
      summary: Analyze a wallet address (sandbox profile)
      description: |
        Returns a risk summary for the given address. Sandbox profile runs
        only cheap modules on the backend: label lookup, balance + tx count,
        contract bytecode check, and recent activity in a 7-day window.
        Expensive modules (token flow, cross-chain, clustering, graph) are
        skipped at compute time and the corresponding response fields are
        gated per the policy in the top-level description.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address, network]
              properties:
                address:
                  type: string
                  example: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
                network:
                  type: string
                  example: "eth"
      responses:
        '200':
          description: Sandbox analysis response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxCheckResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/SandboxNotSupported'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'

  /api/v1/sandbox/graph/expand:
    post:
      operationId: sandboxGraphExpand
      tags: [Graph]
      summary: Sandbox graph preview (depth=1, last 7 days, capped)
      description: |
        Sandbox graph preview is for **integration testing**. It is limited
        to depth 1, recent activity, and capped nodes/edges. Upgrade for
        full historical graph expansion via paid `/api/graph/expand`.

        Returns a node/edge graph in the same broad shape as paid
        `/api/graph/expand` (aggregated counterparty edges with
        `from`/`to`/`value`/`valueWei`/`txCount`/`firstTx`/`lastTx`/
        `tokenBreakdown`) so a sandbox client can be re-pointed at paid
        without rewriting response handling.

        ### Sandbox limits
        - `depth`: max 1 (silently clamped; reported in `_sandbox.truncated_fields.depth`)
        - `nodes`: max 20
        - `edges`: max 30
        - History window: last 7 days only
        - Tx fetch cap: 100 per request
        - No clusters, no entity expansion, no cross-chain graph, no AI
        - **No report persistence**, **no usage row**, **no credit charge**

        ### Supported networks
        EVM family — `eth`, `arbitrum`, `optimism`, `base`, `polygon`,
        `avalanche`, `zksync`, `scroll`, `celo`, `cronos`, `moonbeam`,
        plus `bsc` and `tron`. **13 networks total** in current
        production. Other networks (sol, btc, ltc, ton, cosmos, cardano,
        xrp, plus `linea`, `fantom`, `polygon_zkevm`) return **422**
        with `details.errorCode = "NETWORK_NOT_SUPPORTED_IN_SANDBOX"` —
        no silent fallback to a paid traversal.

        > `linea`, `fantom`, `polygon_zkevm` were removed from the
        > supported set in audit #46 (2026-05-04) because the upstream
        > analyzer returns 503 for these chains. They will return when
        > the underlying provider config is fixed.

        ### Auth
        API key only (sandbox `ocr_test_*` or paid `ocr_live_*`). JWT/session
        auth is rejected with 401 `API_KEY_REQUIRED`. Paid keys are allowed
        so that paid customers can integrate-test against the sandbox shape;
        the response is always sandbox-scoped regardless of key type.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [address, network]
              properties:
                address:
                  type: string
                  example: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
                network:
                  type: string
                  enum:
                    - eth
                    - arbitrum
                    - optimism
                    - base
                    - polygon
                    - avalanche
                    - zksync
                    - scroll
                    - celo
                    - cronos
                    - moonbeam
                    - bsc
                    - tron
                  example: "eth"
                depth:
                  type: integer
                  minimum: 1
                  maximum: 1
                  default: 1
                  description: |
                    Depth is silently clamped to 1. Higher values are
                    reported back via `_sandbox.truncated_fields.depth`.
      responses:
        '200':
          description: Sandbox graph preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxGraphResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Sandbox graph preview temporarily unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: false }
                  error: { type: string, example: "Sandbox graph preview temporarily unavailable. Please try again later." }
                  code: { type: string, example: "SANDBOX_GRAPH_UNAVAILABLE" }

  # Note: /api/analyze/estimate is NOT exposed on api.onchainrisk.io. It is an
  # internal preflight; direct external calls would 404. Intentionally
  # omitted from this spec.

  /api/user/me:
    get:
      operationId: sandboxGetMe
      tags: [Account]
      summary: Current user profile (with sandbox markers)
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserMeSandbox'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/user/usage:
    get:
      operationId: sandboxGetUsage
      tags: [Account]
      summary: Current usage and limit status
      description: |
        Returns current period usage against plan limit plus available credits.
        Free tier returns rolling-daily window; paid tiers return monthly.
      responses:
        '200':
          description: Usage info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageInfo'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: ocr_test_* (legacy keys may still use ocr_live_*)

  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, example: false }
              error: { type: string, example: "unauthorized" }

    BadRequest:
      description: Invalid request (e.g. address too large for sandbox)
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, example: false }
              error: { type: string, example: "address_too_large_for_sandbox" }
              estimated_tx: { type: integer }
              upgrade_url: { type: string }

    SandboxNotSupported:
      description: |
        Endpoint not available for sandbox keys. The body is actionable and
        machine-readable. `error.code` stays `sandbox_not_supported` for
        backward compatibility; `error.reason` carries the finer distinction:
        `paid_only` when the endpoint exists but is a paid feature, or
        `unsupported` when the path is not part of the sandbox API at all
        (e.g. a guessed/nonexistent endpoint shape). No risk or report data is
        returned. Sandbox reports are never saved (`_sandbox.reports_saved`
        is always `false`); persistent reports and retrieval are a paid plan
        feature.
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, example: false }
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum: [sandbox_not_supported]
                    description: Preserved for backward compatibility.
                  reason:
                    type: string
                    enum: [paid_only, unsupported]
                  upgrade_required: { type: boolean }
                  message: { type: string }
                  endpoint:
                    type: string
                    description: "The blocked request, e.g. 'POST /api/v1/check/deep'."
                  docs_url: { type: string }
                  upgrade_url: { type: string }
                  hint: { type: string }
                required: [code, reason, upgrade_required, message, endpoint]
              _sandbox:
                type: object
                properties:
                  allowed_endpoint: { type: string, example: "POST /api/v1/check" }
                  reports_saved: { type: boolean, example: false }
          examples:
            paid-only:
              summary: A real, paid-only endpoint (reason=paid_only)
              value:
                success: false
                error:
                  code: "sandbox_not_supported"
                  reason: "paid_only"
                  upgrade_required: true
                  message: "This endpoint is available on paid API plans."
                  endpoint: "POST /api/v1/check/deep"
                  docs_url: "https://api.onchainrisk.io/sandbox-docs"
                  upgrade_url: "https://onchainrisk.io/pricing"
                  hint: "Sandbox keys can call POST /api/v1/check with { address, network }."
                _sandbox:
                  allowed_endpoint: "POST /api/v1/check"
                  reports_saved: false
            unsupported:
              summary: Path not part of the sandbox API — guessed/nonexistent (reason=unsupported)
              value:
                success: false
                error:
                  code: "sandbox_not_supported"
                  reason: "unsupported"
                  upgrade_required: false
                  message: "This endpoint is not part of the sandbox API."
                  endpoint: "GET /api/v1/address/0xabc"
                  docs_url: "https://api.onchainrisk.io/sandbox-docs"
                  upgrade_url: "https://onchainrisk.io/pricing"
                  hint: "Sandbox keys can call POST /api/v1/check with { address, network }."
                _sandbox:
                  allowed_endpoint: "POST /api/v1/check"
                  reports_saved: false

    ValidationFailed:
      description: |
        Address failed validation before any scan was performed. HTTP status
        is **422** with envelope `{ success: false, error: ErrorResponse }`.
        `error.details.errorCode` carries the granular reason.
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, example: false }
              error: { $ref: '#/components/schemas/ErrorResponse' }
          examples:
            address-network-mismatch:
              summary: Tron address submitted with network=eth
              value:
                success: false
                error:
                  message: "Validation failed"
                  code: "VALIDATION_ERROR"
                  details:
                    address: "Address format does not match selected network. The address looks like a tron address, but network was set to eth."
                    errorCode: "ADDRESS_NETWORK_MISMATCH"
                    detectedFamily: "tron"
                    requestedNetwork: "eth"
            invalid-address:
              summary: Whitespace-only address
              value:
                success: false
                error:
                  message: "Validation failed"
                  code: "VALIDATION_ERROR"
                  details:
                    address: "Address is required."
                    errorCode: "INVALID_ADDRESS"

    RateLimited:
      description: Rate limit exceeded (token bucket)
      headers:
        Retry-After:
          schema: { type: integer }
          description: Seconds until at least 1 token refills
      content:
        application/json:
          schema:
            type: object
            properties:
              success: { type: boolean, example: false }
              error: { type: string, example: "rate_limit_exceeded" }
              bucket:
                type: string
                enum: [per_key, per_ip]
              retry_after_seconds: { type: integer }
              upgrade_url: { type: string }

  schemas:
    Coverage:
      type: object
      description: |
        Per-chain coverage disclosure block. Present on every report response
        regardless of stage — clients should NEVER need to special-case its absence.

        Stage taxonomy:
          - `ga`       — General Availability: full historical depth within stated window.
          - `rollout`  — Active migration / soak window. Coverage windows may temporarily vary.
          - `preview`  — Pre-v1: reports may have incomplete depth or gaps.
          - `degraded` — Known operational incident; see `warning` and `incident_url`.

        **Client integration requirement:** clients integrating OnChainRisk are
        REQUIRED to surface the `coverage.disclosure` field to end users when
        `stage != ga`. For `stage in [preview, degraded]`, clients MUST surface
        the `warning` field prominently.

        Sandbox responses use the SAME Coverage schema as paid responses — no
        schema drift between the two surfaces. Sandbox does not carry a
        sandbox-specific stage; the stage reflects the underlying chain's
        canonical maturity from the public coverage matrix.

        Canonical per-chain status matrix: see the `matrix_url` link.
      required: [stage, window, data_path, as_of, disclosure, matrix_url]
      properties:
        stage:
          type: string
          enum: [ga, rollout, preview, degraded]
          description: |
            Coverage maturity for this chain.
        window:
          type: [string, 'null']
          example: "30d"
          description: |
            Trailing coverage window (e.g. "30d", "90d"). May be `null` for
            chains in `preview` stage where no window is yet committed.
        data_path:
          type: string
          example: "self_hosted_nitro_clickhouse"
          description: |
            Production data path label (informational; not a user-facing
            commitment).
        as_of:
          type: string
          format: date
          example: "2026-05-04"
          description: ISO date when this coverage status was last verified.
        disclosure:
          type: string
          description: |
            Disclosure text appropriate for this stage. Clients SHOULD surface
            this to end users when `stage != ga`.
        warning:
          type: string
          description: |
            Strong warning text. Present (REQUIRED) when `stage in [preview, degraded]`.
            Clients MUST surface this prominently.
        incident_url:
          type: string
          format: uri
          description: |
            Incident status URL. May be present when `stage = degraded`.
        matrix_url:
          type: string
          format: uri
          example: "https://onchainrisk.io/coverage"
        served_from:
          type: string
          enum: [hot, archive, direct_node, direct_api, mixed]
          description: |
            Optional hybrid read-model disclosure. Which read path served this
            report: `hot` (own indexer / hot store), `archive` (replayed from
            archive), `direct_node` (point node lookup), `direct_api`
            (third-party API fallback, e.g. Moralis), or `mixed` (hot/indexer
            data combined with a point lookup such as `eth_getCode` is_contract).
            Absent when the producer does not yet emit hybrid disclosure.
        historical_completeness:
          type: string
          enum: [within_window, replayed_from_archive, partial_via_fallback, unknown_before_window]
          description: |
            Optional hybrid read-model disclosure. Depth completeness of the
            served data: `within_window` (full depth within the stated window),
            `replayed_from_archive` (archive replay restored depth),
            `partial_via_fallback` (a third-party fallback supplied partial
            depth), or `unknown_before_window` (the indexer window limited how
            far back depth is known). Absent when not emitted by the producer.
        fallback_used:
          type: boolean
          description: |
            Optional hybrid read-model disclosure. `true` when a third-party /
            direct-API fallback (e.g. Moralis) supplied the analytical data.
            A point lookup such as `eth_getCode` / is_contract alone does NOT
            set this. Absent when not emitted by the producer.
        source_mode:
          type: string
          description: |
            Optional hybrid read-model disclosure. Free-form source label, e.g.
            `mixed` (hot indexer + point lookup), `hot:<data_path>`, or
            `fallback:moralis`. Informational; not an enum. Absent when not
            emitted by the producer.
        coverage_window:
          type: [string, 'null']
          example: "30d"
          description: |
            Optional alias of `window` — same value, provided for hybrid
            read-model consumers that key on `coverage_window`. Does NOT change
            the meaning of `window`. Absent when not emitted by the producer.
      example:
        stage: rollout
        window: "30d"
        data_path: self_hosted_nitro_clickhouse
        as_of: "2026-05-04"
        disclosure: "OnChainRisk's multi-chain coverage is in active rollout..."
        matrix_url: https://onchainrisk.io/coverage
        served_from: hot
        historical_completeness: within_window
        fallback_used: false
        source_mode: "hot:self_hosted_nitro_clickhouse"
        coverage_window: "30d"

    ErrorResponse:
      type: object
      description: |
        Stable error envelope for validation and business-rule failures.
        The shape mirrors the live API response:

        ```json
        { "success": false, "error": ErrorResponse }
        ```

        Required fields (`code` + `message`) are always populated; `details`
        carries structured diagnostic context and is present on validation
        failures. Clients should treat unknown fields as additive
        (no `additionalProperties: false`).
      required: [code, message]
      properties:
        code:
          type: string
          description: Outer envelope code. Always `VALIDATION_ERROR` for the validation family.
          enum:
            - VALIDATION_ERROR
        message:
          type: string
          description: Short, stable human-readable summary.
        details:
          type: object
          description: |
            Granular context. For validation failures the shape below is stable;
            for other error classes the API may return different keys.
          properties:
            address:
              type: string
              description: Human-readable reason specific to the failing address.
            errorCode:
              type: string
              description: |
                Granular validation reason. Stable machine-readable code.

                  - `INVALID_ADDRESS` — empty, wrong format, whitespace-only.
                  - `UNSUPPORTED_NETWORK` — `network` not in the supported list.
                  - `COULD_NOT_DETECT_NETWORK` — address format unrecognised and `network` omitted.
                  - `INVALID_ADDRESS_CHECKSUM` — decode succeeded, family checksum failed (Tron / BTC-legacy / LTC-legacy). Solana decode failures surface as `INVALID_ADDRESS` because Solana is not checksum-based.
                  - `ADDRESS_NETWORK_MISMATCH` — detected family inconsistent with requested `network`.
              enum:
                - INVALID_ADDRESS
                - UNSUPPORTED_NETWORK
                - COULD_NOT_DETECT_NETWORK
                - INVALID_ADDRESS_CHECKSUM
                - ADDRESS_NETWORK_MISMATCH
            detectedFamily:
              type: [string, 'null']
              description: |
                Address family detected from the input. Null when the format
                was unrecognisable. ENS names are resolved through a legacy
                path and are intentionally not part of the strict family
                contract documented here.
            requestedNetwork:
              type: [string, 'null']
              description: Normalized network string from the request, if any.

    Counterparty:
      type: object
      description: |
        Wallet counterparty entry (inbound or outbound). In sandbox responses
        the containing array is always empty; this schema documents the
        shape clients can rely on when upgrading to paid.
      properties:
        address: { type: string }
        label: { type: [string, 'null'] }
        value: { type: string, description: "Native-unit value transferred" }
        valueUsd: { type: [number, 'null'] }
        txCount: { type: integer }
        inbound: { type: boolean }

    Connection:
      type: object
      description: Directed value edge used by graph views. Empty in sandbox.
      properties:
        address: { type: string }
        value: { type: string }
        direction:
          type: string
          enum: [in, out]

    ContractDeployment:
      type: object
      description: Contract deployed by the address. Empty in sandbox.
      properties:
        contractAddress: { type: string }
        txHash: { type: string }
        blockNumber: { type: integer }

    TokenTransfer:
      type: object
      description: |
        ERC20 / SPL / etc. token transfer. Empty in sandbox responses.
      properties:
        txHash: { type: string }
        from: { type: string }
        to: { type: string }
        tokenAddress: { type: string }
        tokenSymbol: { type: [string, 'null'] }
        amount: { type: string }
        timestamp: { type: integer }

    Transaction:
      type: object
      description: |
        Native transaction entry. In sandbox, only the last 7 days are included.
      properties:
        txHash: { type: string }
        from: { type: string }
        to: { type: [string, 'null'] }
        value: { type: string }
        timestamp: { type: integer }
        direction:
          type: string
          enum: [in, out, self]

    FlagDetail:
      type: object
      required: [code, templateKey, defaultEn]
      description: |
        Localization-friendly flag metadata. Use `code` / `templateKey` for
        translation/mapping. `defaultEn` is a display fallback only — it
        may include dynamic values and is not stable across releases.
        Pattern flags use the `pattern.*` namespace; bot flags would use
        `bot.*` (NOT applicable in sandbox — `timing` is null-gated and
        thus `botFlagDetails` is not present in sandbox responses).
        Schema is identical to the paid /api/v1/check FlagDetail
        component (parity-tested).
      properties:
        code:
          type: string
          description: Stable machine-readable identifier. Use this for translation/mapping.
          example: bulk_collection
        templateKey:
          type: string
          description: Namespaced i18n key. `pattern.<code>` for pattern flags.
          example: pattern.bulk_collection
        defaultEn:
          type: string
          description: Current English display fallback. May include dynamic values. Do not use as translation key.
          example: "BULK COLLECTION pattern: 24 inbound TXs in 600s"
        severity:
          type: string
          enum: [critical, high, medium, low]
          nullable: true
          example: medium
        description:
          type: string
          nullable: true
          description: Short stable English explanation of the flag meaning.
          example: "Many sources sent funds within a short window (bulk collection)."

    SandboxCheckResponse:
      type: object
      description: |
        Same core envelope as the paid `/api/v1/check` response, with many
        expensive fields returned as `null` or `[]`. The `_sandbox` root block
        lists which fields are gated for this response. See the top-level
        description "Response Policy" section for details.
      properties:
        address: { type: string }
        network: { type: string }
        riskScore: { type: integer, minimum: 0, maximum: 100 }
        riskLevel:
          type: string
          enum: [low, medium, high, unknown]
        riskConfidence:
          type: string
          enum: [high, medium, low]
          description: |
            Always `"low"` in sandbox - reusing the existing paid enum value
            to signal partial-data analysis without adding a new enum value.
        dataQuality:
          type: string
          enum: [full, partial, degraded]
          description: Always `"partial"` in sandbox.
        riskNote:
          type: [string, 'null']
        addressInfo:
          type: object
          properties:
            type: { type: string, enum: [eoa, contract, unknown] }
            balance: { type: string }
            balanceUsd: { type: [number, 'null'] }
            nativePriceUsd: { type: [number, 'null'] }
            txCount: { type: integer }
            firstSeen: { type: [string, 'null'] }
            lastSeen: { type: [string, 'null'] }
        labels:
          type: array
          items: { type: string }
        usdPrices:
          type: [object, 'null']
        analysisTime: { type: integer, description: "Milliseconds" }
        timestamp: { type: string, format: date-time }

        # Truncated arrays - real items, bounded
        patternFlags:
          type: array
          items: { type: string }
          maxItems: 5
          description: |
            Legacy display strings, capped at the top 5 flags in sandbox.
            For localization use `code` / `templateKey` from the
            index-aligned `patternFlagDetails` array.
        patternFlagDetails:
          type: array
          maxItems: 5
          description: |
            Localization-friendly metadata for patternFlags. Capped at the
            same top 5 items and INDEX-ALIGNED with `patternFlags`
            (`patternFlagDetails[i]` corresponds to `patternFlags[i]`).
            Use `code` / `templateKey` for translation/mapping.
            `defaultEn` is a display fallback only — may include dynamic
            values; not stable across releases.
            Note: in sandbox `timing` is null-gated, so `botFlagDetails`
            (which lives inside `timing` for paid responses) is NOT
            present in sandbox.
          items:
            $ref: '#/components/schemas/FlagDetail'
          example:
            - code: bulk_collection
              templateKey: pattern.bulk_collection
              defaultEn: "BULK COLLECTION pattern: 24 inbound TXs in 600s"
              severity: medium
              description: "Many sources sent funds within a short window (bulk collection)."
            - code: ofac_sanctions_match
              templateKey: pattern.ofac_sanctions_match
              defaultEn: "OFAC/sanctions list match"
              severity: critical
              description: "Address matches an OFAC/sanctions list."
        transactionHistory:
          type: array
          description: In sandbox, only transactions from the last 7 days.
          items: { $ref: '#/components/schemas/Transaction' }

        # Gated arrays - always [] in sandbox, but item schema preserved for codegen / typing
        topCounterparties:
          type: array
          items: { $ref: '#/components/schemas/Counterparty' }
          description: |
            Always `[]` in sandbox responses. Schema preserved so TypeScript /
            other generated types remain meaningful when you upgrade to paid.
          x-ocr-sandbox-always-empty: true
        addressConnections:
          type: array
          items: { $ref: '#/components/schemas/Connection' }
          description: Always `[]` in sandbox responses.
          x-ocr-sandbox-always-empty: true
        contractDeployments:
          type: array
          items: { $ref: '#/components/schemas/ContractDeployment' }
          description: Always `[]` in sandbox responses.
          x-ocr-sandbox-always-empty: true
        tokenTransferHistory:
          type: array
          items: { $ref: '#/components/schemas/TokenTransfer' }
          description: Always `[]` in sandbox responses.
          x-ocr-sandbox-always-empty: true

        # Gated objects - always null in sandbox
        crossChain:
          type: [object, 'null']
          description: Always `null` in sandbox. Populated on paid plans.
          x-ocr-sandbox-always-null: true
        tokenFlow:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        clusters:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        temporalClusters:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        nftWashTrading:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        exchangeDeposits:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        osintIntelligence:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        railgun:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        defiSwaps:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        contractAnalysis:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        honeypot:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        tokenScore:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        timing:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        fundedBy:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        contractInfo:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true
        dataCompleteness:
          type: [object, 'null']
          description: Always `null` in sandbox.
          x-ocr-sandbox-always-null: true

        # Sandbox marker block
        _sandbox:
          $ref: '#/components/schemas/SandboxMarker'

    SandboxMarker:
      type: object
      description: |
        Present only in responses returned to sandbox API keys. Paid responses
        never include this field.
      required: [profile, coverage_days, reports_saved, gated_fields, truncated_fields, upgrade_url, docs_url]
      properties:
        profile:
          type: string
          enum: [sandbox]
        coverage_days:
          type: integer
          enum: [7]
        reports_saved:
          type: boolean
          enum: [false]
          description: Sandbox responses are never persisted as reports.
        gated_fields:
          type: array
          items: { type: string }
          description: |
            Field names that are gated in this response (null or [] or
            omitted). Use this as source of truth, not a hardcoded list.
        truncated_fields:
          type: object
          additionalProperties: { type: string }
          description: Map of field name to truncation reason.
        upgrade_url: { type: string, format: uri }
        docs_url: { type: string, format: uri }

    SandboxGraphResponse:
      type: object
      description: |
        Sandbox graph preview response. Aggregated counterparty edges in
        the same broad shape as paid `/api/graph/expand`, capped to 20
        nodes / 30 edges and windowed to the last 7 days. Integrators can
        re-point clients at paid `/api/graph/expand` later without
        rewriting response handling.

        **Window invariant**: every aggregated edge field
        (`txCount`, `value`, `valueWei`, `firstTx`, `lastTx`,
        `tokenBreakdown`) reflects ONLY transactions whose timestamp
        falls inside the 7-day window. A counterparty whose only
        interaction is older than 7 days is absent from the response;
        a counterparty with mixed history shows the recent-only slice.
      required: [success, data]
      properties:
        success: { type: boolean, example: true }
        data:
          type: object
          required: [address, network, nodes, edges, _sandbox]
          properties:
            address: { type: string }
            network: { type: string }
            nodes:
              type: array
              maxItems: 20
              items: { $ref: '#/components/schemas/SandboxGraphNode' }
            edges:
              type: array
              maxItems: 30
              items: { $ref: '#/components/schemas/SandboxGraphEdge' }
            partial:
              type: boolean
              description: |
                True when at least one of: tx fetch hit the cap, nodes
                were truncated, edges were truncated, or the upstream
                analysis service flagged the response as partial.
            _sandbox:
              $ref: '#/components/schemas/SandboxGraphMarker'

    SandboxGraphNode:
      type: object
      description: |
        Counterparty node. Schema mirrors paid `/api/graph/expand` node
        shape so a sandbox client can switch to paid without changes.
      required: [address]
      properties:
        address: { type: string }
        label: { type: [string, 'null'] }
        isTarget: { type: boolean, default: false }
        totalValue:
          type: string
          description: |
            Native value formatted (e.g. "1.5" ETH/BNB/TRX). String to
            preserve precision across networks.
        txCount: { type: integer, minimum: 0 }
        tokens:
          type: array
          items: { type: string }

    SandboxGraphEdge:
      type: object
      description: |
        Aggregated edge between target and counterparty. Same field names
        as paid `/api/graph/expand` edges. Sandbox-only deviations are
        documented per-field below.
      required: [from, to, value, valueWei, txCount]
      properties:
        from: { type: string }
        to: { type: string }
        fromLabel: { type: [string, 'null'] }
        toLabel: { type: [string, 'null'] }
        value:
          type: string
          description: Native value formatted; sandbox windowed to last 7 days.
        valueWei:
          type: string
          description: Native value in raw integer units.
        txCount: { type: integer, minimum: 1 }
        firstTx:
          type: [integer, 'null']
          description: Unix timestamp of first interaction within the 7d window.
        lastTx:
          type: [integer, 'null']
          description: Unix timestamp of last interaction within the 7d window.
        tokenBreakdown:
          type: array
          description: Per-token volume breakdown (subset in sandbox).
          items:
            type: object

    SandboxGraphMarker:
      type: object
      description: |
        Sandbox marker for graph preview responses. Distinct from
        `SandboxMarker` (which is shaped for `/api/v1/check`). Both share
        `profile`, `coverage_days`, `gated_fields`, `truncated_fields`,
        `upgrade_url`, `docs_url`; this variant adds graph-specific
        `limits` and `partial`.
      required:
        - profile
        - coverage_days
        - reports_saved
        - limits
        - truncated_fields
        - gated_fields
        - upgrade_url
        - docs_url
      properties:
        profile:
          type: string
          enum: [sandbox]
        coverage_days:
          type: integer
          enum: [7]
        reports_saved:
          type: boolean
          enum: [false]
        partial:
          type: boolean
          description: Mirrors `data.partial` for clients that read the marker.
        limits:
          type: object
          required: [depth, max_nodes, max_edges]
          properties:
            depth: { type: integer, enum: [1] }
            max_nodes: { type: integer, enum: [20] }
            max_edges: { type: integer, enum: [30] }
        truncated_fields:
          type: object
          additionalProperties: { type: string }
          description: |
            Map of field-name → truncation reason. Always includes
            `history: "last_7_days"`. Adds `depth: "max_1"` when the
            request asked for depth > 1, `nodes: "max_20"` when nodes
            were truncated, `edges: "max_30"` when edges were truncated.
        gated_fields:
          type: array
          items: { type: string }
          description: |
            Paid-only fields not present in the sandbox graph response —
            includes `clusters`, `entityExpansion`, `crossChainGraph`,
            `historicalTraversal`, `aiSummary`.
        upgrade_url: { type: string, format: uri }
        docs_url: { type: string, format: uri }

    UserMeSandbox:
      type: object
      description: |
        User profile returned when the request used a sandbox API key. The
        `plan` field stays as the real subscription tier (billing truth);
        `key_type` and `api_mode` are the sandbox signal.
      properties:
        id: { type: integer }
        email: { type: string, format: email }
        plan:
          type: string
          enum: [free, pro, business, enterprise]
          description: Real subscription plan. Never overridden to "sandbox".
        key_type:
          type: string
          enum: [sandbox]
          description: Present only when request used a sandbox API key.
        api_mode:
          type: string
          enum: [sandbox]
          description: Effective access mode for this request.

    UsageInfo:
      type: object
      description: |
        Usage counters for the authenticated user. Free tier returns a rolling
        24-hour window; paid tiers return a monthly window. Reset fields are
        omitted for free tier because a rolling window has no fixed reset.
      properties:
        plan:
          type: string
          enum: [free, pro, business, enterprise]
        period:
          type: string
          enum: [daily, monthly]
        queriesUsed: { type: integer }
        queriesLimit: { type: integer }
        queriesRemaining: { type: integer }
        credits:
          type: integer
          description: Purchased overflow credits available.
        periodStart:
          type: [string, 'null']
          format: date-time
          description: Not returned for free tier (rolling window).
        periodEnd:
          type: [string, 'null']
          format: date-time
        resetsAt:
          type: [string, 'null']
          format: date-time