ASTEROID XRPL Holders API

openapi: 3.2.0
info:
  title: ASTEROID XRPL Agent Holders 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: Holders
paths:
  /api/v1/holders:
    get:
      operationId: getHolderDistribution
      summary: Trust-line and holder counts
      description: Complete marker-chain enumeration of the issuer's trust lines on one validated ledger, with an explicit completeness flag and counting methodology.
      responses:
        '200':
          description: Holder envelope
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/response-envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/holder-state'
        '503':
          description: Upstream ledger unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      tags:
      - Holders
components:
  schemas:
    holder-state:
      title: ASTEROID trust-line and holder counts
      type: object
      required:
      - trustLines
      - nonZeroHolders
      - complete
      - pagesRead
      - pageLimit
      - methodology
      additionalProperties: false
      properties:
        trustLines:
          type:
          - integer
          - 'null'
          minimum: 0
        nonZeroHolders:
          type:
          - integer
          - 'null'
          minimum: 0
        complete:
          type: boolean
        pagesRead:
          type: integer
          minimum: 0
        pageLimit:
          type: integer
          minimum: 1
        methodology:
          type: string
    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
    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