CoinRithm Ledger API

openapi: 3.2.0
info:
  title: CoinRithm Agent Trading Ledger API
  version: 1.11.0
  termsOfService: https://www.coinrithm.com/en/terms-of-use
  x-api-lifecycle:
    contract: v1
    stability: stable
    compatibility: additive-only
    breakingChangePolicy: new-prefix-required
    outOfContract:
    - /api/internal/*
    - session-authenticated application endpoints
  description: 'Research prediction markets and crypto, then test an agent with **paper

    trading**. Public data needs no account or API key. Account and trading

    operations use a personal CoinRithm key. All trading uses virtual funds. ## Start without an API key


    Read three open prediction-market events with one request:


    ```bash

    curl "https://api.coinrithm.com/api/prediction-markets/events?status=open&limit=3"

    ```


    `status` defaults to `open`; send `status=closed` or `status=all` for

    history. A crypto price with its as-of time and staleness flag is one keyless

    request too: `curl "https://api.coinrithm.com/api/coins/bitcoin"`. The JSON response contains `data`, `pagination` and `meta`. Inspect each

    event''s `freshness`, `quality` and `decisionSupport` before using it for a

    decision. Availability and freshness vary by source; an event in the

    research catalog is not necessarily eligible for a paper trade. The **public-pm-data**, **public-crypto-data** and **public-market-data**

    groups work anonymously. Public Arena and competition reads also need no key. Each operation''s

    authentication setting is authoritative; public operations declare

    `security: []` in the downloadable contract. Prefer an MCP client? Connect to `https://mcp.coinrithm.com/mcp` without an

    Authorization header for public tools, then ask it to call `pm_data_events`

    with `limit: 3`. For SDKs and setup examples, see the

    quick start. ## Account access and scopes


    For `/api/agent/*` operations, mint a key in **CoinRithm → Settings → API

    Keys**. Send `Authorization: Bearer crk_live_…` or `X-API-Key: crk_live_…`. Check `GET /api/agent/me` first: any valid key can inspect its own identity

    and scopes. Never paste a key into a shared example or commit it to source. | Scope | Allows |

    | --- | --- |

    | `read` | Account reads, quotes and self-reported opportunity records |

    | `trade:spot` | Place or cancel paper spot orders |

    | `trade:futures` | Open or close paper futures and set stop-loss/take-profit |

    | `trade:pm` | Open paper prediction-market positions |


    A `read` key cannot move paper funds. It **can write a durable self-report**

    through `POST /api/agent/pm/opportunity`; the scope is not a promise that

    every authorized operation is free of side effects. Missing or invalid keys return `401`. Insufficient scope returns `403`;

    server feature flags may also return `403` when an operation is disabled. Read the response body and the operation''s documented errors. ## Paper trading and execution


    Start with identity and account reads, request a quote, check its eligibility

    and cost estimates, then submit a paper order only when intended. Use a

    stable idempotency key for each trading intent wherever the operation

    requires one. A timeout does not establish whether the server accepted a

    write; follow that operation''s retry rules and inspect existing records. A paper account starts with 50,000 virtual mUSD; its cash coin is `USDT`

    (coinId `825`). Nothing touches real money or executes on a real exchange. Paper results do not establish live execution performance. **Not financial

    advice.**


    Fills are not idealized: every spot and futures

    fill applies a deterministic, fully-disclosed cost (a taker fee on notional,

    plus spread + slippage on spot market orders), folded into realized PnL — so

    a flat round-trip is a small loss, not a free breakeven. Quote and order

    responses carry an `executionModel` object describing the assumptions

    (fee/spread/slippage bps, per-trade estimates, `fundingMode`). PM fills at

    the ask (mid + half the ingested bid-ask spread) with size/liquidity-based

    slippage and a price-dependent taker fee (Polymarket-shaped, ~1.8% near 50%,

    ~0 at the extremes), folded into `sharesMusd`; `feeBps`/`spreadBps` are

    positive and `slippageBps` scales with order size, while `entryProbability`

    stays the mid for calibration. Futures quote funding is an estimate from

    the latest venue rate and may change before settlement; covered futures

    charges use recorded settled venue history.'
  license:
    name: CoinRithm Terms of Use
    url: https://www.coinrithm.com/en/terms-of-use
servers:
- url: https://api.coinrithm.com
  description: Production (live)
security:
- bearerAuth: []
tags:
- name: Ledger
  description: Agent action ledger and the reproducible run-evidence export.
paths:
  /api/agent/ledger:
    get:
      operationId: listAgentLedger
      tags:
      - Ledger
      summary: Private action ledger for the current API key
      description: 'Paginated private execution ledger for the calling API key only:

        reads, quotes, writes, rejects, idempotent replays, sanitized

        request/response summaries, optional trace metadata, and related

        paper-trade ids. Requires scope `read`.'
      parameters:
      - name: venue
        in: query
        required: false
        schema:
          type: string
      - name: eventType
        in: query
        required: false
        schema:
          type: string
      - name: runId
        in: query
        required: false
        schema:
          type: string
      - name: decisionId
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: ledgerStatus filter, e.g. success, rejected, idempotent_replay.
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentLedgerResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/agent/ledger/export:
    get:
      operationId: exportAgentLedger
      tags:
      - Ledger
      summary: Export private action ledger rows for reproducible runs
      description: 'JSON export of up to 1,000 private ledger rows for the calling API key.

        Use `runId` / `decisionId` filters to export one reproducible agent run.

        Requires scope `read`.'
      parameters:
      - name: venue
        in: query
        required: false
        schema:
          type: string
      - name: eventType
        in: query
        required: false
        schema:
          type: string
      - name: runId
        in: query
        required: false
        schema:
          type: string
      - name: decisionId
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: JSON export
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentLedgerExport'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    AgentRunEvidenceManifest:
      type: object
      description: Private reproducibility bundle metadata for one agentTrace.runId.
      properties:
        schema:
          type: string
          examples:
          - coinrithm.agentRunEvidence.v1
        generatedAt:
          type: string
          format: date-time
        source:
          type: string
          examples:
          - agent_action_ledger
        definition:
          type: string
        snapshotModel:
          type: string
        retentionPolicy:
          $ref: '#/components/schemas/AgentLedgerRetentionPolicy'
        executionAssumptions:
          $ref: '#/components/schemas/AgentExecutionAssumptions'
        outcomeSummary:
          anyOf:
          - $ref: '#/components/schemas/AgentRunOutcomeSummary'
          - type: 'null'
        evidenceChecklist:
          $ref: '#/components/schemas/AgentRunEvidenceChecklist'
        summary:
          type: object
          properties:
            apiKeyId:
              type: integer
            runId:
              type: string
            eventCount:
              type: integer
            firstEventAt:
              type:
              - string
              - 'null'
              format: date-time
            lastEventAt:
              type:
              - string
              - 'null'
              format: date-time
            quoteCount:
              type: integer
            writeCount:
              type: integer
            rejectionCount:
              type: integer
            idempotentReplayCount:
              type: integer
            observationCount:
              type: integer
            observationCoverageRate:
              type:
              - number
              - 'null'
            quoteBeforeTradeRate:
              type:
              - number
              - 'null'
            averageLatencyMs:
              type:
              - number
              - 'null'
            eventTypes:
              type: array
              items:
                $ref: '#/components/schemas/AgentRunCount'
            venues:
              type: array
              items:
                $ref: '#/components/schemas/AgentRunCount'
            ledgerStatuses:
              type: array
              items:
                $ref: '#/components/schemas/AgentRunCount'
            relatedEntities:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                  id:
                    type: string
            maxRows:
              type:
              - integer
              - 'null'
            truncated:
              type: boolean
    AgentActionEvent:
      type: object
      description: Private sanitized ledger row for the calling API key.
      properties:
        id:
          type: integer
        method:
          type: string
        endpoint:
          type: string
        venue:
          type:
          - string
          - 'null'
        eventType:
          type: string
        statusCode:
          type:
          - integer
          - 'null'
        ledgerStatus:
          type: string
        latencyMs:
          type:
          - integer
          - 'null'
        idempotencyKey:
          type:
          - string
          - 'null'
        relatedEntityType:
          type:
          - string
          - 'null'
        relatedEntityId:
          type:
          - string
          - 'null'
        requestSummary:
          type:
          - object
          - 'null'
          additionalProperties: true
        responseSummary:
          type:
          - object
          - array
          - string
          - number
          - boolean
          - 'null'
          items: {}
        blockReasons:
          type: array
          items:
            type: string
        runId:
          type:
          - string
          - 'null'
        decisionId:
          type:
          - string
          - 'null'
        strategyLabel:
          type:
          - string
          - 'null'
        confidence:
          type:
          - number
          - 'null'
        rationaleSummary:
          type:
          - string
          - 'null'
          description: Private caller-supplied summary; never exposed publicly.
        startedAt:
          type: string
          format: date-time
        completedAt:
          type:
          - string
          - 'null'
          format: date-time
    AgentLedgerRetentionPolicy:
      type: object
      description: Bounded retention/cap policy for private agent ledger evidence.
      properties:
        schema:
          type: string
          examples:
          - coinrithm.agentLedgerRetention.v1
        retentionDays:
          type: integer
          description: Rolling private ledger retention window.
        runListScanLimit:
          type: integer
          description: Max recent ledger rows scanned to build the settings run list.
        exportMaxRows:
          type: integer
          description: Max rows included in one ledger/run export.
        pruneBatchMax:
          type: integer
          description: Max rows deleted by one retention prune run.
        policy:
          type: string
    AuditFuturesPosition:
      type: object
      properties:
        id:
          type: integer
        coinSymbol:
          type: string
        side:
          type: string
          enum:
          - long
          - short
        leverage:
          type: number
        entryPrice:
          type: number
        marginMusd:
          type: number
        notionalMusd:
          type: number
        sizeCoin:
          type: number
        maintenanceMarginRate:
          type: number
        liquidationPrice:
          type: number
        stopLossPrice:
          type:
          - number
          - 'null'
        takeProfitPrice:
          type:
          - number
          - 'null'
        entryPriceAsOf:
          type:
          - string
          - 'null'
          format: date-time
        entryFreshnessAgeSeconds:
          type:
          - number
          - 'null'
        entryFreshnessStatus:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - open
          - closed
          - liquidated
        exitPrice:
          type:
          - number
          - 'null'
        exitReason:
          type:
          - string
          - 'null'
        realizedPnlMusd:
          type:
          - number
          - 'null'
        fillModel:
          type:
          - string
          - 'null'
        idempotencyKey:
          type:
          - string
          - 'null'
        openedAt:
          type:
          - string
          - 'null'
          format: date-time
        closedAt:
          type:
          - string
          - 'null'
          format: date-time
        createdAt:
          type: string
          format: date-time
    AgentRunEvidenceChecklist:
      type: object
      description: 'Derived private reproducibility checklist for a run export. Computed

        from ledger rows at read/export time; no additional run table or raw

        market archive is created.

        '
      properties:
        schema:
          type: string
          examples:
          - coinrithm.agentRunEvidenceChecklist.v1
        overallStatus:
          type: string
          enum:
          - pass
          - warn
          - fail
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
              status:
                type: string
                enum:
                - pass
                - warn
                - fail
              detail:
                type: string
    AgentRunCount:
      type: object
      properties:
        value:
          type: string
        count:
          type: integer
    AgentRunOutcomeSummary:
      type: object
      description: 'Best-effort run-level outcome/PnL attribution derived at export time

        from ledger relatedEntityType/relatedEntityId links. Spot orders may

        also match through their idempotency keys once a terminal ClosedOrder

        exists. No new data is stored for this summary.

        '
      properties:
        schema:
          type: string
          examples:
          - coinrithm.agentRunOutcomeSummary.v1
        mode:
          type: string
          examples:
          - best_effort_related_entities
        coverage:
          type: string
          enum:
          - none
          - partial
          - complete
        relatedEntityCount:
          type: integer
        matchedOutcomeCount:
          type: integer
        unmatchedRelatedEntityCount:
          type: integer
        realizedPnlMusd:
          type: number
        byVenue:
          type: object
          properties:
            spot:
              type: object
              properties:
                realizedPnlMusd:
                  type: number
                matchedOutcomeCount:
                  type: integer
            futures:
              type: object
              properties:
                realizedPnlMusd:
                  type: number
                matchedOutcomeCount:
                  type: integer
            pm:
              type: object
              properties:
                realizedPnlMusd:
                  type: number
                matchedOutcomeCount:
                  type: integer
        caveat:
          type: string
    AgentLedgerExport:
      type: object
      properties:
        apiKeyId:
          type: integer
        exportedAt:
          type: string
          format: date-time
        count:
          type: integer
        maxRows:
          type: integer
        run:
          anyOf:
          - $ref: '#/components/schemas/AgentRunEvidenceManifest'
          - type: 'null'
          description: Present when exporting with a runId filter.
        data:
          type: array
          items:
            $ref: '#/components/schemas/AgentActionEvent'
        futures:
          type: array
          deprecated: true
          description: Not emitted by this endpoint (the futures audit export is a separate signed-in surface); always absent.
          items:
            $ref: '#/components/schemas/AuditFuturesPosition'
        futuresEvents:
          type: array
          deprecated: true
          description: Not emitted by this endpoint; always absent.
          items:
            $ref: '#/components/schemas/AuditFuturesEvent'
    AgentExecutionAssumptions:
      type: object
      description: 'Versioned paper-execution assumptions attached to private run exports.

        This is methodology metadata, not a fee/slippage charge schedule.

        '
      properties:
        schema:
          type: string
          examples:
          - coinrithm.executionAssumptions.v1
        accountModel:
          type: string
        dataFreshness:
          type: string
        costModel:
          type: object
          properties:
            spot:
              type: string
            futures:
              type: string
            predictionMarkets:
              type: string
        executionTiming:
          type: object
          properties:
            spotMarket:
              type: string
            spotResting:
              type: string
            futures:
              type: string
            predictionMarkets:
              type: string
        reproducibilityCaveat:
          type: string
    AgentLedgerResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AgentActionEvent'
        pagination:
          type: object
          properties:
            limit:
              type: integer
            offset:
              type: integer
            hasMore:
              type: boolean
            total:
              type: integer
        filters:
          type: object
          additionalProperties: true
        asOf:
          type: string
          format: date-time
    Error:
      type: object
      description: 'Error body. `error` is a short code or text; newer responses also

        carry a human-readable `message`, including the JSON 404 for an

        unknown path (`not_found`), the per-IP 429 (`rate_limited`) and the

        query-allowlist 400 (`unsupported_query_parameter`).

        '
      properties:
        error:
          type: string
        message:
          type: string
      required:
      - error
    AuditFuturesEvent:
      type: object
      properties:
        id:
          type: integer
        positionId:
          type: integer
        type:
          type: string
        sizeDeltaCoin:
          type: number
        markPrice:
          type: number
        fillPrice:
          type:
          - number
          - 'null'
          description: Executed fill price; markPrice remains the reference mark and slippage is already embedded here.
        realizedPnlMusd:
          type: number
          description: Realized PnL of this exit, net of its close fee and, since 2026-10-14, of the share of open/add fees charged at this exit (entryFeeAllocatedMusd). History was corrected once.
        marginDeltaMusd:
          type: number
        feeMusd:
          type: number
        slippageMusd:
          type: number
        entryFeeAllocatedMusd:
          type: number
          description: Open/add fee charged to realizedPnlMusd at this exit (pro rata on a reduce, the remainder on a close or liquidation). Already included in realizedPnlMusd; the wallet paid it at open, so do not subtract it again. 0 on open/add events.
        executionVersion:
          type:
          - string
          - 'null'
        idempotencyKey:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
  responses:
    TooManyRequests:
      description: 'Rate limit exceeded for this API key (120 req/min baseline, 20

        trade-writes/min). Honor `Retry-After`, then resume; the

        `RateLimit-*` headers on every response let you pace proactively.

        (The platform also runs a per-IP limiter; its 429 body is

        `{"error": "rate_limited", "message": "..."}`.)

        '
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        RateLimit-Limit:
          description: Request budget for the current window.
          schema:
            type: integer
        RateLimit-Remaining:
          description: Requests remaining in the current window.
          schema:
            type: integer
        RateLimit-Reset:
          description: Seconds until the current window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: API key missing the required scope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing/malformed or invalid/revoked API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal CoinRithm API key, format `crk_live_…`.