ASTEROID XRPL Quote API

openapi: 3.2.0
info:
  title: ASTEROID XRPL Agent Quote 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: Quote
paths:
  /api/v1/quote:
    get:
      operationId: getSwapQuote
      summary: Indicative AMM estimate
      description: Indicative bidirectional ASTEROID/XRP AMM estimate. The response carries a quote identifier, the methodology identifier and version, the validated ledger index, an expiry after which the estimate must be discarded, the exact calculation inputs and a link to the published test vectors. Not executable, models the single AMM pool only, and never signs, submits or prepares a transaction.
      parameters:
      - name: direction
        in: query
        required: true
        schema:
          type: string
          enum:
          - xrp-to-asteroid
          - asteroid-to-xrp
      - name: side
        in: query
        required: false
        schema:
          type: string
          enum:
          - exact-in
          - exact-out
          default: exact-in
      - name: amount
        in: query
        required: true
        schema:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
      - name: slippageTolerancePct
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Quote envelope
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/response-envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/quote-response'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '503':
          description: Pool unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      tags:
      - Quote
    post:
      operationId: postSwapQuote
      summary: Indicative AMM estimate (JSON body)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/quote-request'
      responses:
        '200':
          description: Quote envelope
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/response-envelope'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/quote-response'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
        '503':
          description: Pool unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      tags:
      - Quote
components:
  schemas:
    quote-response:
      title: Indicative ASTEROID AMM quote
      type: object
      required:
      - tokenId
      - direction
      - assetIn
      - assetOut
      - request
      - lifecycle
      - calculation
      - quote
      - pool
      - warnings
      - error
      - executable
      - claimStatus
      - methodology
      - limitations
      additionalProperties: false
      properties:
        tokenId:
          type: string
        direction:
          type: string
          enum:
          - xrp-to-asteroid
          - asteroid-to-xrp
        assetIn:
          type: string
        assetOut:
          type: string
        request:
          type: object
          required:
          - side
          - amount
          - slippageTolerancePct
          additionalProperties: false
          properties:
            side:
              type: string
              enum:
              - exact-in
              - exact-out
            amount:
              type: string
            slippageTolerancePct:
              type:
              - string
              - 'null'
        lifecycle:
          type: object
          required:
          - quoteId
          - methodologyId
          - methodologyVersion
          - ledgerIndex
          - observedAt
          - maxAgeMs
          - expiresAt
          - remainingMs
          - cache
          - testVectors
          additionalProperties: false
          properties:
            quoteId:
              type: string
              description: 'Identifier for this estimate. It is a correlation handle only: it reserves nothing, cannot be redeemed and cannot be executed.'
            methodologyId:
              type: string
            methodologyVersion:
              type: string
            ledgerIndex:
              type:
              - integer
              - 'null'
            observedAt:
              type: string
              format: date-time
            maxAgeMs:
              type: integer
              minimum: 0
            expiresAt:
              type: string
              format: date-time
              description: observedAt + maxAgeMs, always measured from the original ledger observation and never restarted by a cache hit. After this instant the estimate must be discarded and the pool re-read. Expiry does not mean the estimate was ever executable.
            remainingMs:
              type: integer
              minimum: 0
              description: 'Freshness left on the original observation when the estimate was produced: maxAgeMs minus the age of the pool reading. A cache hit never restarts the window, so expiresAt always equals observedAt + maxAgeMs.'
            cache:
              oneOf:
              - $schema: https://json-schema.org/draft/2020-12/schema
                $id: https://asteroidxrpl.com/schemas/v1/cache-freshness-metadata.json
                title: Cache freshness metadata
                description: Age disclosure for a reading served from the bounded single-flight server cache. A cached reading still states the validated ledger index and observation time it was produced from; its age is never hidden.
                type: object
                required:
                - hit
                - cachedAt
                - ageMs
                - ttlMs
                additionalProperties: false
                properties:
                  hit:
                    type: boolean
                    description: True when this response reused a cached reading.
                  cachedAt:
                    type: string
                    format: date-time
                  ageMs:
                    type: integer
                    minimum: 0
                  ttlMs:
                    type: integer
                    minimum: 0
                  key:
                    type: string
              - type: 'null'
            testVectors:
              type: string
              format: uri
        calculation:
          oneOf:
          - $ref: '#/components/schemas/calculation-input'
          - type: 'null'
        quote:
          oneOf:
          - $ref: '#/components/schemas/calculation-result'
          - type: 'null'
        pool:
          type: object
          required:
          - account
          - xrpReserve
          - asteroidReserve
          - tradingFeeUnits
          - tradingFeePct
          additionalProperties: false
          properties:
            account:
              type:
              - string
              - 'null'
            xrpReserve:
              type:
              - string
              - 'null'
              pattern: ^-?[0-9]+(\.[0-9]+)?$
              description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
            asteroidReserve:
              type:
              - string
              - 'null'
              pattern: ^-?[0-9]+(\.[0-9]+)?$
              description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
            tradingFeeUnits:
              type:
              - integer
              - 'null'
            tradingFeePct:
              type:
              - string
              - 'null'
              pattern: ^-?[0-9]+(\.[0-9]+)?$
              description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        warnings:
          type: array
          items:
            type: object
            required:
            - code
            - severity
            - message
            additionalProperties: false
            properties:
              code:
                type: string
              severity:
                type: string
                enum:
                - info
                - warning
              message:
                type: string
        error:
          oneOf:
          - type: object
            required:
            - code
            - message
            additionalProperties: false
            properties:
              code:
                type: string
              message:
                type: string
          - type: 'null'
        executable:
          const: false
          description: Always false. This service never produces an executable quote.
        claimStatus:
          type: string
          enum:
          - ledger-verified
          - owner-confirmed
          - independently-sourced
          - derived
          - aspirational
          - unresolved
        methodology:
          type: string
        limitations:
          type: array
          items:
            type: string
    calculation-input:
      title: Calculation input
      description: The exact inputs a derived value was computed from, republished so the calculation can be reproduced independently against the published test vectors.
      type: object
      required:
      - formulaId
      - methodologyId
      - methodologyVersion
      - direction
      - side
      - amount
      - poolIn
      - poolOut
      - assetIn
      - assetOut
      - tradingFeeUnits
      - feeFraction
      - slippageTolerancePct
      - rounding
      additionalProperties: false
      properties:
        formulaId:
          type: string
          const: constant-product-swap
        methodologyId:
          type: string
        methodologyVersion:
          type: string
        direction:
          type: string
          enum:
          - xrp-to-asteroid
          - asteroid-to-xrp
        side:
          type: string
          enum:
          - exact-in
          - exact-out
        amount:
          type: string
        poolIn:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        poolOut:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        assetIn:
          type: string
        assetOut:
          type: string
        tradingFeeUnits:
          type: integer
          minimum: 0
        feeFraction:
          type: string
        slippageTolerancePct:
          type:
          - string
          - 'null'
        rounding:
          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
    calculation-result:
      title: Calculation result
      description: The result of a constant-product AMM calculation. Every quantity is an exact decimal string. Indicative and never executable.
      type: object
      required:
      - side
      - amountIn
      - amountOut
      - feeAmountIn
      - tradingFeeUnits
      - tradingFeePct
      - spotPrice
      - effectivePrice
      - priceImpactPct
      - poolUtilisationPct
      - poolInAfter
      - poolOutAfter
      - slippageTolerancePct
      - minimumReceived
      - maximumPaid
      additionalProperties: false
      properties:
        side:
          type: string
          enum:
          - exact-in
          - exact-out
        amountIn:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        amountOut:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        feeAmountIn:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        tradingFeeUnits:
          type: integer
        tradingFeePct:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        spotPrice:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        effectivePrice:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        priceImpactPct:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        poolUtilisationPct:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        poolInAfter:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        poolOutAfter:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        slippageTolerancePct:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        minimumReceived:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
        maximumPaid:
          type:
          - string
          - 'null'
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: Exact decimal string. Never rounded for transport. Null means unreadable, not zero.
    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
    quote-request:
      title: Indicative AMM quote request
      description: Request contract for GET /api/v1/quote (query parameters) and the get_swap_quote MCP tool (arguments). No account, key or credential is ever part of a request.
      type: object
      required:
      - direction
      - amount
      additionalProperties: false
      properties:
        direction:
          type: string
          enum:
          - xrp-to-asteroid
          - asteroid-to-xrp
          description: Which asset is paid in and which is received.
        side:
          type: string
          enum:
          - exact-in
          - exact-out
          default: exact-in
          description: Whether `amount` is the exact input paid or the exact output required.
        amount:
          type: string
          pattern: ^[0-9]+(\.[0-9]+)?$
          description: Positive exact decimal string in units of the asset implied by `side`.
        slippageTolerancePct:
          type:
          - string
          - 'null'
          description: Optional tolerance between 0 and 50, used only to derive minimumReceived / maximumPaid.
    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