ASTEROID XRPL Asset API

openapi: 3.2.0
info:
  title: ASTEROID XRPL Agent Asset 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: Asset
paths:
  /api/v1/asset:
    get:
      operationId: getAssetIdentity
      summary: Canonical identity
      description: Immutable identity plus claim-status-separated project metadata. No ledger read is performed, so provenance.ledgerIndex is null.
      responses:
        '200':
          description: Canonical identity envelope
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/response-envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/identity-response'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      tags:
      - Asset
  /api/v1/asset/evidence:
    get:
      operationId: getAssetEvidence
      summary: Historical ledger evidence
      description: Historical anchors re-validated through the shared XRPL client. A failed upstream lookup yields verificationResult "unavailable", claimStatus "unresolved" and a degraded entry — never an invented success and never a substituted intended value.
      responses:
        '200':
          description: Evidence envelope
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/response-envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/evidence-response'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      tags:
      - Asset
components:
  schemas:
    evidence-response:
      title: Historical evidence response data
      type: object
      required:
      - classification
      - items
      additionalProperties: false
      properties:
        classification:
          type: string
          const: historical-ledger-evidence
        items:
          type: array
          items:
            $ref: '#/components/schemas/ledger-evidence'
    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
    project-identity:
      title: ASTEROID project identity
      type: object
      required:
      - name
      - description
      - descriptionClaimStatus
      - canonicalWebsite
      - network
      - approvalAuthority
      - approvalAuthorityClaimStatus
      - nonAffiliation
      - declaredWallets
      additionalProperties: false
      properties:
        name:
          type: string
        description:
          type: string
        descriptionClaimStatus:
          type: string
          enum:
          - ledger-verified
          - owner-confirmed
          - independently-sourced
          - derived
          - aspirational
          - unresolved
        canonicalWebsite:
          type: string
          format: uri
        network:
          type: string
        approvalAuthority:
          type: string
        approvalAuthorityClaimStatus:
          type: string
          enum:
          - ledger-verified
          - owner-confirmed
          - independently-sourced
          - derived
          - aspirational
          - unresolved
        nonAffiliation:
          type: string
        declaredWallets:
          type: array
          items:
            type: object
            required:
            - address
            - role
            - claimStatus
            - note
            additionalProperties: false
            properties:
              address:
                type: string
              role:
                type: string
              claimStatus:
                type: string
                enum:
                - ledger-verified
                - owner-confirmed
                - independently-sourced
                - derived
                - aspirational
                - unresolved
              note:
                type: string
    canonical-asset:
      title: Canonical ASTEROID asset identity
      type: object
      required:
      - tokenId
      - network
      - networkName
      - issuer
      - currencyHex
      - displaySymbol
      - projectName
      - canonicalWebsite
      - identifierPolicy
      - precisionPolicy
      - claimStatus
      additionalProperties: false
      properties:
        tokenId:
          type: string
          pattern: ^[a-z0-9-]+:r[1-9A-HJ-NP-Za-km-z]{24,34}:[0-9A-F]{40}$
        network:
          type: string
        networkName:
          type: string
        issuer:
          type: string
          pattern: ^r[1-9A-HJ-NP-Za-km-z]{24,34}$
        currencyHex:
          type: string
          pattern: ^[0-9A-F]{40}$
        displaySymbol:
          type: string
        projectName:
          type: string
        canonicalWebsite:
          type: string
          format: uri
        identifierPolicy:
          type: string
        precisionPolicy:
          type: string
        claimStatus:
          type: string
          enum:
          - ledger-verified
          - owner-confirmed
          - independently-sourced
          - derived
          - aspirational
          - unresolved
    ledger-evidence:
      title: Historical ledger evidence item
      type: object
      required:
      - id
      - classification
      - label
      - supportedClaim
      - claimStatus
      - verificationResult
      - transactionHash
      - ledgerIndex
      - transactionResult
      - observedValue
      - expectedValue
      - destination
      - source
      - method
      - detail
      - explorerUrl
      additionalProperties: false
      properties:
        id:
          type: string
        classification:
          type: string
          const: historical-ledger-evidence
        label:
          type: string
        supportedClaim:
          type: string
        claimStatus:
          type: string
          enum:
          - ledger-verified
          - owner-confirmed
          - independently-sourced
          - derived
          - aspirational
          - unresolved
        verificationResult:
          type: string
          enum:
          - verified
          - mismatch
          - unavailable
        transactionHash:
          type: string
          pattern: ^[0-9A-F]{64}$
        ledgerIndex:
          type:
          - integer
          - 'null'
        transactionResult:
          type:
          - string
          - 'null'
        observedValue:
          type:
          - string
          - 'null'
          description: Exact decimal string. Never a binary floating-point number, never coerced to zero.
        expectedValue:
          type:
          - string
          - 'null'
        destination:
          type:
          - string
          - 'null'
        source:
          type: string
        method:
          type: string
        detail:
          type:
          - string
          - 'null'
        explorerUrl:
          type: string
          format: uri
    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
    identity-response:
      title: Canonical identity response data
      type: object
      required:
      - canonicalAsset
      - projectIdentity
      - claimStatuses
      - capabilities
      additionalProperties: false
      properties:
        canonicalAsset:
          $ref: '#/components/schemas/canonical-asset'
        projectIdentity:
          $ref: '#/components/schemas/project-identity'
        claimStatuses:
          type: array
          items:
            type: object
            required:
            - status
            - meaning
            additionalProperties: false
            properties:
              status:
                type: string
                enum:
                - ledger-verified
                - owner-confirmed
                - independently-sourced
                - derived
                - aspirational
                - unresolved
              meaning:
                type: string
        capabilities:
          type: array
          items:
            type: object
            required:
            - name
            - description
            - status
            - interfaces
            - freshness
            - provenanceNote
            - schema
            - limitations
            additionalProperties: false
            properties:
              name:
                type: string
              description:
                type: string
              status:
                type: string
                enum:
                - available
                - legacy-available
                - deprecated
                - unavailable
                - planned
                description: 'available: Gate 1 surface with a published schema. legacy-available: retained pre-Gate-1 surface, callable but unenveloped. deprecated: callable, scheduled for removal. unavailable: declared but not currently callable. planned: not implemented and not callable.'
              interfaces:
                type: array
                items:
                  type: string
              freshness:
                type: string
              provenanceNote:
                type: string
              schema:
                type: string
              limitations:
                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