0G Labs Account API

openapi: 3.2.0
info:
  description: 0G Router is an API gateway between users and the decentralized 0G Compute Provider network.
  title: 0G Router Account API
  termsOfService: https://0g.ai/terms
  contact:
    name: 0G Labs
    url: https://0g.ai
    email: contact@0g.ai
  version: '1.0'
servers:
- url: /v1
tags:
- name: Account
paths:
  /account:
    get:
      security:
      - ManagementKeyAuth: []
      description: 'Returns non-financial metadata for the authenticated wallet: `created_at` and `onboarded_at`. `onboarded_at` is an RFC3339 timestamp once the account has completed or dismissed the new-user onboarding flow, and `null` until then — a client reads it to decide whether to show onboarding. Set it via `POST /account/onboarded`. The value is stored per wallet on the server, so it persists across a cleared cache, another browser, and another device.'
      tags:
      - Account
      summary: Get account
      responses:
        '200':
          description: Account metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.AccountResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
      operationId: getAccount
      x-operation-id-source: derived
  /account/funds:
    get:
      security:
      - ManagementKeyAuth: []
      description: 'Returns a single aggregated view of the caller''s funds so clients don''t have to combine `/account/balance` (Router ledger) with the on-chain `PaymentVault.balanceOf` themselves.


        `total` = `router.subtotal` + `payment_layer.balance`, where `router.subtotal` = `deposit` + `credit` − `pending_charge` (the net Router-ledger position). `total` is the user''s net spendable funds and **may be negative** when outstanding debt exceeds available funds — render the shortfall as "owed to Router". This differs from `/account/balance`''s `total_balance`, which keeps a ≥0 contract for settlement / SDK callers and does NOT subtract pending_charge.


        `payment_layer.balance` is the shared Payment Layer vault balance (`shared_across_products: true` — the vault is a pool across 0G apps, not owned exclusively by Router). `queried_at` is when that balance was actually read from chain; it is cached (~10s), so on a cache hit it can be up to that TTL in the past — treat it as the value''s as-of time, not the request time.


        For the Router-ledger-only view that settlement / SDK / mgmt-key integrations depend on, use `/account/balance` instead.'
      tags:
      - Account
      summary: Get unified account funds
      responses:
        '200':
          description: Unified funds view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.FundsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
      operationId: getAccountFunds
      x-operation-id-source: derived
  /account/usage/daily:
    get:
      security:
      - ManagementKeyAuth: []
      description: Get usage statistics broken down by day for current user, with optional filters
      tags:
      - Account
      summary: Get daily usage statistics
      parameters:
      - description: Filter by API key ID
        name: api_key_id
        in: query
        schema:
          type: string
      - description: 'Filter by source: ''wallet'' (JWT/browser), ''api_key'' (any API key), or omit for all'
        name: source
        in: query
        schema:
          type: string
      - description: Start date (YYYY-MM-DD, inclusive)
        name: start_date
        in: query
        schema:
          type: string
      - description: End date (YYYY-MM-DD, inclusive)
        name: end_date
        in: query
        schema:
          type: string
      - description: 'Filter by trust tier: ''standard'' | ''verified'' | ''private''. Omit for all tiers.'
        name: trust_mode
        in: query
        schema:
          type: string
      - description: 'Extra breakdown dimensions on top of (date, model). Only ''trust_mode'' is supported: pass `dimensions=trust_mode` to split each day/model row per trust tier and emit the `trust_mode` field. Omit (default) for the legacy one-row-per (date, model) shape.'
        name: dimensions
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Daily usage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.DailyUsageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
      operationId: getAccountUsageDaily
      x-operation-id-source: derived
  /account/usage/history:
    get:
      security:
      - ManagementKeyAuth: []
      description: Get usage history for current user, with optional filters
      tags:
      - Account
      summary: Get usage history
      parameters:
      - description: Limit number of records
        name: limit
        in: query
        schema:
          type: integer
          default: 20
      - description: Offset for pagination (legacy). Ignored when `cursor` is set.
        name: offset
        in: query
        schema:
          type: integer
          default: 0
      - description: '[beta] Opaque keyset cursor from a prior page''s `next_cursor`. When set, pages via seek (constant per-page cost, independent of depth) and `offset` is ignored; also forces `include_total=false`.'
        name: cursor
        in: query
        schema:
          type: string
      - description: '[beta] Include the full-set `total` count (default true). Set false to skip the expensive COUNT(*); recommended with `cursor`.'
        name: include_total
        in: query
        schema:
          type: boolean
          default: true
      - description: Filter by model ID
        name: model_id
        in: query
        schema:
          type: string
      - description: Filter by API key ID
        name: api_key_id
        in: query
        schema:
          type: string
      - description: 'Filter by source: ''wallet'' (JWT/browser), ''api_key'' (any API key), or omit for all'
        name: source
        in: query
        schema:
          type: string
      - description: Start date (YYYY-MM-DD, inclusive)
        name: start_date
        in: query
        schema:
          type: string
      - description: End date (YYYY-MM-DD, inclusive)
        name: end_date
        in: query
        schema:
          type: string
      - description: 'Filter by trust tier: ''standard'' | ''verified'' | ''private''. Omit for all tiers.'
        name: trust_mode
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Usage history list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.UsageHistoryResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
      operationId: getAccountUsageHistory
      x-operation-id-source: derived
  /account/usage/stats:
    get:
      security:
      - ManagementKeyAuth: []
      description: Get usage statistics for current user, optionally filtered by API key and date range
      tags:
      - Account
      summary: Get usage statistics
      parameters:
      - description: Filter by API key ID
        name: api_key_id
        in: query
        schema:
          type: string
      - description: 'Filter by source: ''wallet'' (JWT/browser), ''api_key'' (any API key), or omit for all'
        name: source
        in: query
        schema:
          type: string
      - description: Start date (YYYY-MM-DD, inclusive)
        name: start_date
        in: query
        schema:
          type: string
      - description: End date (YYYY-MM-DD, inclusive)
        name: end_date
        in: query
        schema:
          type: string
      - description: 'Filter by trust tier: ''standard'' | ''verified'' | ''private''. Omit for all tiers.'
        name: trust_mode
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Usage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.UsageStatsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorResponse'
      operationId: getAccountUsageStats
      x-operation-id-source: derived
components:
  schemas:
    github_com_0glabs_0g-router_pkg_response.ErrorDetail:
      type: object
      properties:
        code:
          type: string
          example: bad_request
        message:
          type: string
          example: Invalid request
        type:
          type: string
          example: invalid_request
    github_com_0glabs_0g-router_pkg_response.FundsResponse:
      type: object
      properties:
        address:
          type: string
          example: '0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65'
        currency:
          description: 'Currency is the unit of all amount fields: "0g" (wei, default) or "usd"

            (micro-USD). In USD mode there is no vault, so payment_layer.balance is

            "0" and total = router.subtotal = balance + credit. [beta]'
          type: string
          example: 0g
        payment_layer:
          $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.PaymentLayerFunds'
        router:
          $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.RouterLedgerFunds'
        total:
          type: string
          example: '7390000000000000000'
    github_com_0glabs_0g-router_pkg_response.DailyUsageResponse:
      type: object
      properties:
        currency:
          description: 'Currency is the unit of each row''s cost: "0g" (wei) or "usd" (micro-USD).

            The series is filtered to a single currency (the account''s current

            settlement mode for /account; "0g" for the partner /source endpoint).'
          type: string
          example: 0g
        data:
          type: array
          items:
            $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.DailyUsageSummaryEntry'
        object:
          type: string
          example: list
    github_com_0glabs_0g-router_pkg_response.DailyUsageSummaryEntry:
      type: object
      properties:
        cache_write_1h_tokens:
          description: 'CacheWrite1hTokens is the 1-hour-TTL portion of cache_write_tokens summed

            over the day (disjoint from it). Permanent; reflects volume, not billing. [beta]'
          type: integer
          x-stability: beta
          example: 0
        cache_write_tokens:
          type: integer
          x-stability: beta
          example: 0
        cached_tokens:
          description: 'CachedTokens / CacheWriteTokens are the provider-reported cache-READ and

            cache-WRITE (creation) subsets of input_tokens, summed over the day''s

            rows. Permanent (survive usage_logs retention), so a monthly bill can

            break out cache volume and reconcile `cost`. Both reflect volume, not

            billing: cache_write_tokens is non-zero whenever a provider reported

            cache-creation tokens and does NOT by itself imply a premium was charged

            (the premium, when active, only changes how those tokens price into

            `cost`). Disjoint subsets — input_tokens already includes both

            (input_tokens = plain + cached_tokens + cache_write_tokens). [beta]'
          type: integer
          x-stability: beta
          example: 3200
        canonical_id:
          description: 'CanonicalID is the registry-resolved model id this row aggregates.

            Empty only for rows whose underlying on-chain model_id was never in

            the registry (same '''' = "unmapped" sentinel as providers.canonical_id).

            [beta]'
          type: string
          x-stability: beta
          example: glm-5
        cost:
          type: string
          example: '150000000000000'
        date:
          type: string
          example: 2024-01-15
        input_tokens:
          type: integer
          example: 8000
        model_id:
          description: 'ModelID is preserved for one dual-emit milestone and carries the SAME

            value as CanonicalID for /daily responses. Clients should migrate to

            `canonical_id`; the field is dropped after migration.'
          type: string
          example: glm-5
        output_tokens:
          type: integer
          example: 4345
        request_count:
          type: integer
          example: 42
        trust_mode:
          description: 'TrustMode is the trust tier this row aggregates. Emitted only when the

            caller opts in with ?dimensions=trust_mode (and the capability is

            enabled); omitted otherwise, so the default wire shape is one row per

            (date, model) — byte-identical to pre-trust-mode prod regardless of the

            server flag. When emitted, an empty string represents pre-trust-mode

            legacy traffic (logs that predate the dimension); clients render it as

            "Unknown" or filter the series out.'
          type: string
          example: verified
    github_com_0glabs_0g-router_pkg_response.UsageLogEntry:
      type: object
      properties:
        api_key_id:
          type: string
          example: abc12345
        cache_write_1h_tokens:
          description: 'CacheWrite1hTokens is the 1-hour-TTL portion of cache_write_tokens (disjoint

            from it; cache_write_tokens then carries only the default/5-minute portion).

            Only the Anthropic /v1/messages path reports a TTL breakdown; elsewhere it is

            0 and cache_write_tokens carries the whole write count. Reflects volume, not

            billing. [beta]'
          type: integer
          x-stability: beta
          example: 0
        cache_write_tokens:
          description: 'CacheWriteTokens is the provider-reported cache-WRITE (creation) subset of

            input_tokens (the pair of cached_tokens). Non-zero whenever the provider

            reports cache-creation tokens — it reflects volume, not billing: it does

            NOT imply a premium was charged. When a cache-write premium is active it

            prices these tokens above the plain prompt rate in `cost`; otherwise they

            bill at the plain rate. Disjoint from cached_tokens, and input_tokens

            already includes both (input_tokens = plain + cached_tokens +

            cache_write_tokens) — do not add them on top of input_tokens. [beta]'
          type: integer
          x-stability: beta
          example: 0
        cached_tokens:
          description: cache-READ subset of input_tokens (billed at the read-discount rate)
          type: integer
          example: 40
        canonical_id:
          description: 'CanonicalID is the registry-resolved canonical model id captured at

            billing time. Empty when the underlying on-chain `model_id` isn''t a

            registered canonical / alias (same '''' = "unmapped" sentinel as

            providers.canonical_id). Clients that need a non-empty display string

            should render `canonical_id || model_id`. `model_id` remains the

            on-chain literal so per-endpoint drill-down still works. [beta]'
          type: string
          x-stability: beta
          example: glm-5
        cost:
          type: string
          example: '150000000000000'
        created_at:
          type: string
          example: 2024-01-15 10:30:00+00:00
        credit_used:
          type: string
          example: '50000000000000'
        deposit_used:
          type: string
          example: '100000000000000'
        id:
          type: integer
          example: 1
        input_tokens:
          type: integer
          example: 100
        model_id:
          type: string
          example: qwen-2.5-7b-instruct
        output_tokens:
          type: integer
          example: 50
        provider_address:
          type: string
          example: 0x1234...
        request_id:
          type: string
          example: req_abc123
        trust_mode:
          description: 'TrustMode is the trust tier of the provider that served the request.

            Always emitted; empty string for rows that pre-date the dimension

            (clients render as "—"). usage_logs.trust_mode is NOT NULL DEFAULT

            '''' (AutoMigrate creates the column that way), so the value is

            either a tier name or ''''.'
          type: string
          example: verified
    github_com_0glabs_0g-router_pkg_response.RouterLedgerFunds:
      type: object
      properties:
        credit:
          type: string
          example: '3560000000000000'
        deposit:
          type: string
          example: '300000000000000000'
        pending_charge:
          type: string
          example: '0'
        subtotal:
          type: string
          example: '303560000000000000'
    github_com_0glabs_0g-router_pkg_response.PaymentLayerFunds:
      type: object
      properties:
        balance:
          type: string
          example: '7086440000000000000'
        queried_at:
          type: string
          example: 2026-05-25 16:21:00+00:00
        shared_across_products:
          type: boolean
          example: true
    github_com_0glabs_0g-router_pkg_response.UsageStatsResponse:
      type: object
      properties:
        completion_tokens:
          type: integer
          example: 4345
        currency:
          description: 'Currency is the unit of TotalCost: "0g" (wei) or "usd" (micro-USD). The

            figures are already filtered to a single currency (the account''s current

            settlement mode), so a client renders TotalCost in this unit without a

            second lookup and never mislabels wei as USD.'
          type: string
          example: 0g
        prompt_tokens:
          type: integer
          example: 8000
        total_cost:
          type: string
          example: '1000000000000000'
        total_requests:
          type: integer
          example: 42
        total_tokens:
          type: integer
          example: 12345
    github_com_0glabs_0g-router_pkg_response.ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.ErrorDetail'
        request_id:
          type: string
    github_com_0glabs_0g-router_pkg_response.AccountResponse:
      type: object
      properties:
        address:
          type: string
          example: '0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65'
        created_at:
          type: string
          example: 2026-01-15 10:30:00+00:00
        onboarded_at:
          type: string
          example: 2026-01-15 10:35:00+00:00
    github_com_0glabs_0g-router_pkg_response.UsageHistoryResponse:
      type: object
      properties:
        currency:
          description: 'Currency is the unit of each row''s cost/*_used fields: "0g" (wei) or "usd"

            (micro-USD). The list is filtered to a single currency (the account''s

            current settlement mode), so all rows share this unit.'
          type: string
          example: 0g
        data:
          type: array
          items:
            $ref: '#/components/schemas/github_com_0glabs_0g-router_pkg_response.UsageLogEntry'
        limit:
          type: integer
          example: 20
        next_cursor:
          description: 'NextCursor is the opaque token to fetch the next page via `?cursor=`.

            Absent on the last page. [beta]'
          type: string
          x-stability: beta
        object:
          type: string
          example: list
        offset:
          type: integer
          example: 0
        total:
          description: 'Total is the full-set count. Omitted when include_total=false (or when

            paging by cursor). Pointer + omitempty so absence is unambiguous.'
          type: integer
          example: 100
  securitySchemes:
    ApiKeyAuth:
      description: 'API key for inference, file upload, and async image endpoints. Format: "Bearer sk-..."'
      type: apiKey
      name: Authorization
      in: header
    ManagementKeyAuth:
      description: 'Management key for account read and API key management. Capabilities are scope-limited per key (account:read, keys:read, keys:create, keys:manage). Format: "Bearer mk-..."'
      type: apiKey
      name: Authorization
      in: header