openapi: 3.1.0
info:
  title: Nodetrail Institutional Sandbox API (PREVIEW SPEC)
  version: 0.1.0-preview
  description: |
    PREVIEW SPECIFICATION ONLY. This file documents a sandbox API design.
    The sandbox API is not live on nodetrail.io. No keys are issued from this
    site. Answers, when a preview environment is running, come from saved
    fixture data only; there are no live chain reads.
    Intended keys start with the nt_test_ prefix. Rate limits below are
    preview draft values. Service targets are DRAFT TARGETS, NOT AN SLA.
    No prices.
servers:
  - url: https://example.invalid
    description: Placeholder only. These paths are not served on nodetrail.io.
security:
  - sandboxKey: []
paths:
  /api/inst/sandbox/v1/ping:
    get:
      summary: Check that a sandbox key works
      description: Specified behaviour only. Not served on nodetrail.io.
      responses:
        "200": { description: Key accepted, content: { application/json: { schema: { type: object, properties: { ok: { type: boolean }, sandbox: { type: boolean }, keyId: { type: string } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /api/inst/sandbox/v1/assets:
    get:
      summary: List the fixture assets the sandbox can check
      description: Specified behaviour only. Not served on nodetrail.io.
      responses:
        "200": { description: Fixture list, content: { application/json: { schema: { type: object, properties: { sandbox: { type: boolean }, fixtureData: { type: boolean }, assets: { type: array, items: { $ref: "#/components/schemas/Asset" } } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /api/inst/sandbox/v1/check:
    get:
      summary: Fixture report for one asset
      description: Specified behaviour only. Not served on nodetrail.io.
      parameters:
        - { name: chain, in: query, required: true, schema: { type: string, example: base } }
        - { name: address, in: query, required: true, schema: { type: string, pattern: "^0x[0-9a-fA-F]{40}$" } }
      responses:
        "200": { description: Report built from a fixture snapshot, content: { application/json: { schema: { type: object, properties: { sandbox: { type: boolean }, fixtureData: { type: boolean }, liveChainRead: { type: boolean, const: false }, report: { type: object, description: "nodetrail.institutional.report/v1 with contentHash" } } } } } }
        "400": { $ref: "#/components/responses/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/Error" }
        "429": { $ref: "#/components/responses/RateLimited" }
components:
  securitySchemes:
    sandboxKey: { type: http, scheme: bearer, description: "Authorization: Bearer nt_test_<id>_<secret> (preview design; keys are not issued on nodetrail.io)" }
  schemas:
    Asset: { type: object, properties: { chain: { type: string }, address: { type: string }, label: { type: string }, synthetic: { type: boolean }, asOf: { type: [string, "null"] } } }
    Error: { type: object, properties: { error: { type: object, properties: { code: { type: string }, message: { type: string } } } } }
  responses:
    Error: { description: Error, content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
    Unauthorized: { description: "bad_key, revoked or live_key_rejected", content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
    RateLimited: { description: "rate_limited; see Retry-After and X-RateLimit-* headers", content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } } }
