ASTEROID XRPL Supply API

openapi: 3.2.0
info:
  title: ASTEROID XRPL Agent Supply API
  version: 1.0.0
  summary: Machine discovery and canonical identity for the ASTEROID token on XRPL Mainnet.
  description: 'ASTEROID XRPL is an independent, community-led token project built on the XRP Ledger, combining transparent on-chain evidence, creative community culture, and XRPL-native experimentation.


    Canonical token identifier: xrpl-mainnet:rS5LWaqWuzmoiNpzgYJbPvD1bsRZTgDG7:41535445524F4944000000000000000000000000


    Identify this asset only by the full network:issuer:currency_hex identifier. The display symbol ASTEROID alone is not sufficient and does not establish authenticity.


    Live readings are ledger-indexed and cached for a bounded interval: AMM 10s, supply 30s, escrows 60s, holders 120s. Quotes are indicative estimates against the single ASTEROID/XRP AMM pool and are never executable. No endpoint signs, submits or prepares a transaction, and no endpoint accepts a key, a seed or any credential.


    All responses use a shared envelope with schemaVersion, data, provenance, degraded and links. Changing ledger-backed readings carry an observedAt timestamp and a validated ledgerIndex. Missing readings are returned as null with a stable degraded code and are never coerced to zero. Token quantities are exact decimal strings.


    ASTEROID XRPL is an independent community project. It is not affiliated with Ripple, the XRPL Foundation, SpaceX, Polaris Dawn, or ASTEROID projects on other networks.'
  license:
    name: Public read-only
    identifier: CC-BY-4.0
servers:
- url: https://asteroidxrpl.com
tags:
- name: Supply
paths:
  /api/v1/supply:
    get:
      operationId: getSupplyState
      summary: Supply state
      description: Outstanding, escrowed, total and circulating supply as exact decimal strings, plus the original issuance revalidated against its anchor transaction. Unreadable values are null with a degraded code, never zero.
      responses:
        '200':
          description: Supply envelope
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/response-envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/supply-state'
        '503':
          description: Upstream ledger unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      tags:
      - Supply
components:
  schemas:
    error-response:
      title: Error response
      description: The single stable error contract shared by every Gate 1 and Gate 2 REST endpoint and every MCP tool error. A failure is always reported as a stable machine-readable `error.code` with provenance attached — never as a partially populated success body and never as a zero.
      type: object
      required:
      - schemaVersion
      - error
      - provenance
      additionalProperties: false
      properties:
        schemaVersion:
          type: string
        error:
          type: object
          required:
          - code
          - message
          additionalProperties: false
          properties:
            code:
              type: string
            message:
              type: string
        provenance:
          type: object
          required:
          - observedAt
          - ledgerIndex
          - node
          - method
          additionalProperties: false
          properties:
            observedAt:
              type: string
              format: date-time
            ledgerIndex:
              type:
              - integer
              - 'null'
              description: Validated ledger index, or null when no ledger read was performed.
            node:
              type:
              - string
              - 'null'
            method:
              type: string
    supply-state:
      title: ASTEROID supply state
      type: object
      required:
      - tokenId
      - outstanding
      - escrowed
      - totalSupply
      - circulating
      - circulatingSharePct
      - intendedIssuance
      - returnedToIssuer
      - issuanceAnchor
      - claimStatus
      - methodology
      additionalProperties: false
      properties:
        tokenId:
          type: string
        outstanding:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        escrowed:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        totalSupply:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        circulating:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        circulatingSharePct:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        intendedIssuance:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        returnedToIssuer:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        issuanceAnchor:
          type: object
          required:
          - hash
          - ledgerIndex
          - declaredValue
          - declaredDestination
          - revalidated
          - observedValue
          - observedDestination
          - matchesDeclaration
          additionalProperties: false
          properties:
            hash:
              type: string
            ledgerIndex:
              type: integer
            declaredValue:
              type: string
            declaredDestination:
              type: string
            revalidated:
              type: boolean
            observedValue:
              type:
              - string
              - 'null'
              pattern: ^-?[0-9]+(\.[0-9]+)?$
              description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
            observedDestination:
              type:
              - string
              - 'null'
            matchesDeclaration:
              type:
              - boolean
              - 'null'
        claimStatus:
          type: object
          required:
          - outstanding
          - escrowed
          - totalSupply
          - circulating
          - intendedIssuance
          additionalProperties: false
          properties:
            outstanding:
              type: string
              enum:
              - ledger-verified
              - owner-confirmed
              - independently-sourced
              - derived
              - aspirational
              - unresolved
            escrowed:
              type: string
              enum:
              - ledger-verified
              - owner-confirmed
              - independently-sourced
              - derived
              - aspirational
              - unresolved
            totalSupply:
              type: string
              enum:
              - ledger-verified
              - owner-confirmed
              - independently-sourced
              - derived
              - aspirational
              - unresolved
            circulating:
              type: string
              enum:
              - ledger-verified
              - owner-confirmed
              - independently-sourced
              - derived
              - aspirational
              - unresolved
            intendedIssuance:
              type: string
              enum:
              - ledger-verified
              - owner-confirmed
              - independently-sourced
              - derived
              - aspirational
              - unresolved
        methodology:
          type: string
    degraded-item:
      title: Degraded service item
      type: object
      required:
      - code
      - message
      additionalProperties: false
      properties:
        code:
          type: string
          description: Stable machine-readable degradation code.
        message:
          type: string
    response-envelope:
      title: ASTEROID response envelope
      type: object
      required:
      - schemaVersion
      - data
      - provenance
      - degraded
      - links
      additionalProperties: false
      properties:
        schemaVersion:
          type: string
          const: 1.0.0
        data: {}
        provenance:
          type: object
          required:
          - observedAt
          - ledgerIndex
          - node
          - method
          additionalProperties: false
          properties:
            observedAt:
              type: string
              format: date-time
            ledgerIndex:
              type:
              - integer
              - 'null'
              description: Validated ledger index, or null when no ledger read was performed.
            node:
              type:
              - string
              - 'null'
            method:
              type: string
        degraded:
          type: array
          items:
            $ref: '#/components/schemas/degraded-item'
        links:
          type: object
          additionalProperties:
            type: string
externalDocs:
  description: Agent gateway
  url: https://asteroidxrpl.com/agents
x-schema-base: https://asteroidxrpl.com/schemas/v1
x-mcp-endpoint: https://asteroidxrpl.com/mcp