api-doc.yml

openapi: 3.0.1
servers:
  - url: http://localhost:3000/v3
    description: Local development server
  # - url: http://localhost:3000
  #   description: Local development server (default)
  - url: https://xrpspec.com/v3
    description: Public development server
info:
  description: An API server that provides a REST-like interface to the XRP Ledger.
  version: 0.1.0 # TODO: Load from package.json
  title: XRP-API
tags:
  - name: Query
    description: Methods to access data from the XRP Ledger.
  - name: Transact
    description: Methods to submit transactions to the XRP Ledger.
  - name: Meta
    description: Methods to get information about the XRP-API server itself.
paths:
  '/servers/info':
    get:
      tags:
        - Meta
      summary: Get Server Info
      operationId: getServerInfo
      description: Retrieve information about the current status of the XRP-API Server and the rippled server(s) it is connected to.
      responses:
        '200':
          description: The status of the XRP-API server and an array of statuses from the `rippled` server(s) it is connected to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerInfo'
  '/accounts/{address}/info': # Maps to rippled's account_info command
    get:
      tags:
        - Query
      summary: Get Account Info
      operationId: getAccountInfo
      description: |
        Get information about an account in the XRP Ledger. This includes its settings, activity, and XRP balance. It also includes the sequence number of the next valid transaction for this account, which you should use to prepare a transaction from this account. By default, this method returns data from the 'current' (in-progress) ledger, which may change before validation.
      parameters:
        - in: path
          name: address
          description: The account to query.
          required: true
          schema:
            $ref: '#/components/schemas/Address'
        - in: query
          name: ledger_index
          description: (Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers](https://developers.ripple.com/basic-data-types.html#specifying-ledgers))
          required: false
          schema:
            $ref: '#/components/schemas/LedgerIndex'
      responses:
        '200':
          description: A successful response provides the account data, and information about the ledger version that was used to provide this data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountInfo'
        '400':
          description: The request was not properly formatted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleAPIError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleAPIError'
  '/accounts/{address}/settings': # Maps to ripple-lib's getSettings method
    get:
      tags:
        - Query
      summary: Get Account Settings
      operationId: getAccountSettings
      description: |
        Get an account's settings. These are the settings that can be modified by the user. By default, this method returns data from the 'current' (in-progress) ledger, which may change before validation.
      parameters:
        - in: path
          name: address
          description: The account to query.
          required: true
          schema:
            $ref: '#/components/schemas/Address'
        - in: query
          name: ledger_index
          description: (Optional) The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers](https://xrpl.org/basic-data-types.html#specifying-ledgers))
          required: false
          schema:
            $ref: '#/components/schemas/LedgerIndex'
      responses:
        '200':
          description: A successful response contains the settings data for the requested account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountSettings'
        '400':
          description: The request was not properly formatted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleAPIError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleAPIError'
  '/accounts/{address}/transactions': # Maps to ripple-lib's getTransactions method
    get:
      tags:
        - Query
      summary: Get Account Transactions
      operationId: getAccountTransactions
      description: |
        Get a selection of transactions that affected the specified account.
      parameters:
        - in: path
          name: address
          description: The account to query.
          required: true
          schema:
            $ref: '#/components/schemas/Address'
        - in: query
          name: ledger_index
          description: The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying Ledgers](https://xrpl.org/basic-data-types.html#specifying-ledgers))
          required: false
          schema:
            $ref: '#/components/schemas/LedgerIndex'
      responses:
        '200':
          description: A successful response provides a list of transactions that affected the specified account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountTransactions'
        '400':
          description: The request was not properly formatted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleAPIError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleAPIError'
  '/preparations/payments':
    get:
      tags:
        - Transact
      summary: Prepare a Payment
      operationId: preparePayment
      description: |
        Prepare a payment. Provide the source, destination, currency, and value (amount) as query parameters. XRP-API will perform some pre-flight checks, and auto-fill the Fee, Sequence, and LastLedgerSequence fields.
      parameters:
        - in: query
          name: source
          description: The address of the account sending the payment.
          required: false
          schema:
            $ref: '#/components/schemas/Address'
        - in: query
          name: destination
          description: The address of the account that will receive the payment.
          required: false
          schema:
            $ref: '#/components/schemas/Address'
        - in: query
          name: currency
          description: The currency to send.
          required: false
          schema:
            $ref: '#/components/schemas/Currency'
        - in: query
          name: value
          description: The value of the amount to send.
          required: false
          schema:
            type: string
        - in: query
          name: maxLedgerVersionOffset
          description: Offset from the current validated ledger version to the highest ledger version that the transaction can be included in. This effectively serves as the transaction's expiration time, after which it is invalid. Transactions are typically validated within 2-3 ledgers, but transactions that are signed manually and/or offline may need longer validity times. A ledger is created every 3-4 seconds. For example, a value of `500` would prepare a transaction that will be valid for approximately 25-30 minutes.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A Prepared Payment Transaction, with min_ledger and max_ledger fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreparedPaymentTransaction'
        '400':
          description: The request was not properly formatted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleAPIError'
  '/payments':
    put:
      tags:
        - Transact
      summary: Sign and/or submit a payment
      operationId: signSubmitPayment
      description: |
        Sign a prepared payment transaction and/or submit a transaction to the XRP Ledger network. For signing, the sending account must match an account secret that the XRP-API server is configured with.
      requestBody:
        description: A transaction to sign and/or submit.
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/PaymentTransaction'
                - $ref: '#/components/schemas/SignedTransaction'
            examples:
              paymentTransactionExample:
                $ref: '#/components/examples/paymentTransactionExample'

      responses:
        '200':
          description: A successful response provides the native XRP Ledger format for the transaction, the transaction's identifying hash, and the preliminary result of processing the transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionStatus'
        '400':
          description: The request was not properly formatted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleAPIError'
    post:
      tags:
        - Transact
      summary: Create, sign, and submit a payment
      operationId: createSignSubmitPayment
      description: |
        Create and a payment transaction, and submit it to the XRP Ledger network. The sending account must match an account address and secret the XRP-API server is configured with.
      requestBody:
        description: A transaction object and instructions.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentObjectAndInstructions'
            examples:
              Example_Payment:
                summary: Send an XRP-to-XRP payment.
                value:
                  submit: true
                  payment:
                    source_address: 'rBEXjfD3MuXKATePRwrk4AqgqzuD9JjQqv'
                    source_tag: 123
                    source_amount:
                      value: '5000000'
                      currency: 'drops'
                    destination_address: 'r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59'
                    destination_tag: 456
                    destination_amount:
                      value: '5000000'
                      currency: 'drops'
      responses:
        '200':
          description: A successful response provides the native XRP Ledger format for the transaction, the transaction's identifying hash, and the preliminary result of processing the transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionStatus'
        '400':
          description: The request was not properly formatted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleAPIError'
  '/transactions/{transaction_id}':
    get:
      tags:
        - Query
        - Transact
      summary: Get Transaction
      operationId: getTransaction
      description: Look up the status and details of a transaction. By default, this method only returns data from ledger versions that have been validated by consensus.
      parameters:
        - in: path
          name: transaction_id
          description: The ID of the transaction to retrieve.
          required: true
          schema:
            $ref: '#/components/schemas/TransactionID'
        - in: query
          name: min_ledger
          description: (Optional) Use this with max_ledger to specify a range of up to 1000 ledger indexes, starting with this ledger (inclusive). If the server cannot find the transaction, it confirms whether it was able to search all the ledgers in the requested range. (Requires rippled v1.5.0+)
          required: false
          example: 55420000
          schema:
            type: number
        - in: query
          name: max_ledger
          description: (Optional) Use this with min_ledger to specify a range of up to 1000 ledger indexes, ending with this ledger (inclusive). If the server cannot find the transaction, it confirms whether it was able to search all the ledgers in the requested range. (Requires rippled v1.5.0+)
          required: false
          example: 55420500
          schema:
            type: number
      responses:
        '200':
          description: Transaction object. (Note that this command may successfully find the transaction even if it is included in a ledger outside the range of min_ledger to max_ledger.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppliedTransaction'
        '400':
          description: The request was not properly formatted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RippleAPIError'
        '404':
          description: The transaction was not included in a fully-validated ledger version that the server has available. If you provided both the min_ledger and max_ledger fields in the request, the 404 txnNotFound response includes the searched_all field (requires rippled v1.5.0+).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/RippleAPIError'
                  - type: object
                    properties:
                      searched_all:
                        type: boolean
                        description: (Omitted unless the request provided min_ledger and max_ledger) If true, the server was able to search all of the specified ledger versions, and the transaction was in none of them. If false, the server did not have all of the specified ledger versions available, so it is not sure if one of them might contain the transaction. (Requires rippled v1.5.0+)
        '500':
          description: One of the [Universal Errors](https://xrpl.org/error-formatting.html#universal-errors) occurred.

  '/apiDocs':
    get:
      tags:
        - Meta
      operationId: getApiDoc
      summary: Get API Docs
      description: Return the API specification this server is using.
      responses:
        '200':
          description: API specification document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiDoc'
  '/ping':
    get:
      tags:
        - Meta
      operationId: getPing
      summary: Ping
      description: Ping the server to confirm that it is online.
      responses:
        '200':
          description: A response with an empty body to indicate that the server is online and functional.

components:
  schemas:
    RippleAPIError:
      description: A wrapper for one or more error messages that occurred when processing a request.
      type: object
      required:
      - message
      - errors
      properties:
        message:
          type: string
          description: A human-readable error message summarizing the problem(s) that occurred.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
          description: A list of errors that occurred when processing this request.
    ErrorItem:
      type: object
      required:
      - message
      - code
      properties:
        code:
          type: integer
        message:
          type: string
    ServerInfo:
      required:
        - server_version
      properties:
        server_version:
          type: string
          description: The version number of this XRP-API server, in [SemVer format](https://semver.org/).
        rippled_servers:
          type: array
          description: Server information from each `rippled` server this XRP-API server is connected to.
          items:
            $ref: '#/components/schemas/RippledServerInfo'
    RippledServerInfo:
      required:
      - buildVersion
      - completeLedgers
      - hostID
      - ioLatencyMs
      - lastClose
      - loadFactor
      - peers
      - pubkeyNode
      - serverState
      - validatedLedger
      - validationQuorum
      type: object
      properties:
        buildVersion:
          type: string
          description: The version number of the running rippled version.
        completeLedgers:
          pattern: '[0-9,-]+'
          type: string
          description: Range expression indicating the sequence numbers of the ledger versions the local rippled has in its database. It is possible to be a disjoint sequence, e.g. “2500-5000,32570-7695432”.
        fetchPack:
          type: number
        hostID:
          type: string
          description: On an admin request, returns the hostname of the server running the rippled instance; otherwise, returns a unique four letter word.
        ioLatencyMs:
          type: number
          description: Amount of time spent waiting for I/O operations to be performed, in milliseconds. If this number is not very, very low, then the rippled server is probably having serious load issues.
        jqTransOverflow:
          type: string
        load:
          $ref: '#/components/schemas/Load'
        lastClose:
          $ref: '#/components/schemas/LastClose'
        loadFactor:
          type: number
          description: The load factor the server is currently enforcing, as a multiplier on the base transaction fee. The load factor is determined by the highest of the individual server’s load factor, cluster’s load factor, and the overall network’s load factor.
        peerDisconnects:
          type: string
        peerDisconnectsResources:
          type: string
        peers:
          minimum: 0
          type: integer
          description: How many other rippled servers the node is currently connected to.
          format: int32
        pubkeyNode:
          type: string
          description: Public key used to verify this node for internal communications; this key is automatically generated by the server the first time it starts up. (If deleted, the node can just create a new pair of keys.)
        pubkeyValidator:
          type: string
          description: '*(Admin only)* Public key used by this node to sign ledger validations.'
        serverState:
          $ref: '#/components/schemas/ServerState'
        serverStateDurationUs:
          type: string
          description: The amount of time, in microseconds, that the server has continuously been in the present state (`full`, `syncing`, etc.)
        stateAccounting:
          type: object
          description: Total duration spent in and every transition to various server states. This can be useful for tracking the long-term health of your server's connectivity to the network.
        time:
          type: string
        uptime:
          type: number
          description: Number of consecutive seconds that the server has been operational.
        validatedLedger:
          $ref: '#/components/schemas/ValidatedLedger'
        validationQuorum:
          type: number
          description: Minimum number of trusted validations required in order to validate a ledger version. Some circumstances may cause the server to require more validations.
        validatorList:
          type: object
      additionalProperties: false
    Load:
      title: Load
      required:
      - jobTypes
      - threads
      type: object
      properties:
        jobTypes:
          type: array
          description: '*(Admin only)* Information about the rate of different types of jobs being performed by the server and how much time it spends on each.'
          items:
              type: object
              properties:
                avgTime:
                  type: number
                jobType:
                  type: string
                peakTime:
                  type: number
                perSecond:
                  type: number
        threads:
          type: number
          description: '*(Admin only)* The number of threads in the server’s main job pool, performing various operations.'
      description: '*(Admin only)* Detailed information about the current load state of the server.'
    LastClose:
      title: LastClose
      required:
      - convergeTimeS
      - proposers
      type: object
      properties:
        convergeTimeS:
          type: number
          description: The time it took to reach a consensus for the last ledger closing, in seconds.
        proposers:
          minimum: 0
          type: integer
          description: Number of trusted validators participating in the ledger closing.
          format: int32
      description: Information about the last time the server closed a ledger.
    ServerState:
      title: ServerState
      enum:
      - disconnected
      - connected
      - syncing
      - tracking
      - full
      - validating
      - proposing
      type: string
      description: A string indicating to what extent the server is participating in the network. See [Possible Server States](https://developers.ripple.com/rippled-server-states.html) for more details.
      example: disconnected
    ValidatedLedger:
      title: ValidatedLedger
      required:
      - age
      - baseFeeXRP
      - hash
      - reserveBaseXRP
      - reserveIncrementXRP
      - ledgerVersion
      type: object
      properties:
        age:
          minimum: 0
          type: integer
          description: The time since the ledger was closed, in seconds.
          format: int32
        baseFeeXRP:
          pattern: ^[0-9]*[.]?[0-9]+([eE][-+]?[0-9]+)?$
          type: string
          description: Base fee, in XRP. This may be represented in scientific notation such as 1e-05 for 0.00005.
        hash:
          pattern: ^[A-F0-9]{64}$
          type: string
          description: Unique hash for the ledger, as an uppercase hexadecimal string.
        reserveBaseXRP:
          pattern: ^[0-9]*[.]?[0-9]+([eE][-+]?[0-9]+)?$
          type: string
          description: Base fee, in XRP. This may be represented in scientific notation such as 1e-05 for 0.00005.
        reserveIncrementXRP:
          pattern: ^[0-9]*[.]?[0-9]+([eE][-+]?[0-9]+)?$
          type: string
          description: Base fee, in XRP. This may be represented in scientific notation such as 1e-05 for 0.00005.
        ledgerVersion:
          minimum: 0
          type: integer
          description: Identifying sequence number of this ledger version.
          format: int32
      description: Information about the fully-validated ledger with the highest sequence number (the most recent).
    Address:
      description: The address of an XRP Ledger account.
      type: string
      pattern: '^r[A-HJ-NP-Za-km-z1-9]{24,34}$|^X[A-HJ-NP-Za-km-z1-9]{46}$|^T[A-HJ-NP-Za-km-z1-9]{46}$'
      example: TVp3kyJBH9YhnHcxEwT5ccj3pWN1Z1qYWx3Eq37XV1yGjKj
    TransactionID:
      description: The identifying hash of a transaction.
      type: string
      pattern: '^[0-9A-F]{64}$'
      example: E08D6E9754025BA2534A78707605E0601F03ACE063687A0CA1BDDACFCD1698C7

    PreparedPaymentTransaction:
      description: A payment transaction with min_ledger and max_ledger fields.
      allOf:
        - $ref: '#/components/schemas/PaymentTransaction'
        - type: object
          required:
            - min_ledger
            - max_ledger
          properties:
            min_ledger:
              type: integer
              description: Assuming this transaction has not been submitted in the past, this is the lowest ledger index this transaction can appear in.
            max_ledger:
              type: integer
              description: Highest ledger index this transaction can appear in. Same value as LastLedgerSequence.

    AppliedTransaction:
      description: An applied transaction contains the fields of the Transaction object as well as some additional fields.
      allOf:
        - $ref: '#/components/schemas/TransactionCommonFields'
        - type: object
          required:
            - hash
            - ledger_index
            - meta
            - validated
          properties:
            hash:
              type: string
              description: The hash value that uniquely identifies this transaction. Included only if the transaction was signed and submitted.
            ledger_index:
              type: integer # unsigned
              description: The ledger index of the ledger that includes this transaction.
            meta:
              type: object
              description: Various metadata about the transaction.
            validated:
              type: boolean
              description: True if this data is from a validated ledger version; if omitted or set to false, this data is not final.

    AccountInfo:
      required:
        - account_data
      properties:
        account_data:
          $ref: '#/components/schemas/AccountData'
        ledger_current_index:
          type: integer
          description: (Omitted if `ledger_index` is provided instead) The sequence number of the most-current ledger, which was used when retrieving this information. The information does not contain any changes from ledgers newer than this one.
        ledger_index:
          type: integer
          description: (Omitted if `ledger_current_index` is provided instead) The sequence number of the ledger used when retrieving this information. The information does not contain any changes from ledgers newer than this one.
        validated:
          type: boolean
          description: True if this data is from a validated ledger version; if omitted or set to false, this data is not final.
    AccountSettings:
      # required:
        # The following could be added in the future:
        # - ledger_index
        # - validated
      properties:
        disallowIncomingXRP:
          type: boolean
          description: (Optional) Client applications should not send XRP to this account. Not enforced by rippled.
        domain:
          type: string
          description: (Optional) The domain that owns this account, as a hexadecimal string representing the ASCII for the domain in lowercase.
        emailHash:
          type: string
          nullable: true
          description: (Optional) Hash of an email address to be used for generating an avatar image. Conventionally, clients use Gravatar to display this image. Use `null` to clear.
        requireDestinationTag:
          type: boolean
          description: (Optional) Account requires incoming payments to specify a destination tag.
        passwordSpent:
          type: boolean
          description: (Optional) Account has used its free SetRegularKey transaction.
        disableMasterKey:
          type: boolean
          description: If the master key is disabled, `true`; `false` otherwise.
        regularKey:
          $ref: '#/components/schemas/Address'
        signers:
          type: object
          description: (Optional) Settings that determine what sets of accounts can be used to sign a transaction on behalf of this account using multisigning.
        tickSize:
          type: number
          description: (Optional) Tick size to use for offers involving a currency issued by this address. The exchange rates of those offers is rounded to this many significant digits. Valid values are 3 to 15 inclusive, or 0 to disable.
        transferRate:
          type: number
          nullable: true
          description: (Optional) The fee to charge when users transfer this account’s issuances, as the decimal amount that must be sent to deliver 1 unit. Has precision up to 9 digits beyond the decimal point. Use `null` to set no fee.
        walletLocator:
          type: string
          nullable: true
          description: (Optional) Transaction hash or any other 64 character hexadecimal string, that may or may not represent the result of a hash operation. Use `null` to clear.
        # The following could be added in the future:
        # ledger_index:
        #   type: integer
        #   description: (Omitted if `ledger_current_index` is provided instead) The sequence number of the ledger used when retrieving this information. The information does not contain any changes from ledgers newer than this one.
        # validated:
        #   type: boolean
        #   description: True if this data is from a validated ledger version; if omitted or set to false, this data is not final.
      additionalProperties: false
    AccountTransactions:
      type: object
      properties:
        transactions:
          type: array
          description: A list of transactions to affect the account.
          minItems: 0
          uniqueItems: true
          items:
            $ref: '#/components/schemas/TransactionCommonFields'
        minLedgerVersion:
          type: integer
          description: The minimum ledger index searched when looking for transactions affecting this account.
        validated:
          type: boolean
          description: If `true`, all the transaction outcomes in this response come from validated ledgers, so they are final and immutable.
    AccountData:
      description: The raw [AccountRoot object](https://xrpl.org/accountroot.html) of the account, as stored in the XRP Ledger.
      type: object
      required:
        - LedgerEntryType
        - Account
        - Balance
        - Flags
        - OwnerCount
        - PreviousTxnID
        - PreviousTxnLgrSeq
        - Sequence
      properties:
        Account:
          $ref: '#/components/schemas/Address'
        Balance:
          type: string
          description: The XRP balance of the account, in integer "drops of XRP", where 1000000 drops = 1 XRP.
        Flags:
          type: integer
          description: A bitwise map of settings applied to this account.
        LedgerEntryType:
          type: string
        OwnerCount:
          type: integer
        PreviousTxnID:
          type: string
        PreviousTxnLgrSeq:
          type: integer
        RegularKey:
          $ref: '#/components/schemas/Address'
        Sequence:
          type: integer
        index:
          pattern: ^[A-F0-9]{64}$
          type: string
      additionalProperties: false
    LedgerIndex:
      oneOf:
        - type: string
          enum:
            - validated
            - closed
            - current # default
        - type: integer
    PaymentObjectAndInstructions:
      title: Payment object and instructions
      description: Payment object (specification) and instructions on how to execute it.
      type: object
      required:
      - payment
      - submit
      properties:
        payment:
          $ref: '#/components/schemas/PaymentObject'
        instructions:
          $ref: '#/components/schemas/Instructions'
        submit:
          type: boolean
          description: |
            If `false`, the server will not submit the transaction to the network. Instead, it will only return the following additional fields in the response: `tx_json`, `tx_blob`, and `id` (hash).
    PaymentObject:
      title: Payment Object
      description: A payment object (specification).
      type: object
      properties:
        source_address:
          # description: The account sending the payment (the source account).
          $ref: '#/components/schemas/Address'
        source_tag:
          type: number
        source_amount:
          $ref: '#/components/schemas/Amount'
        source_slippage:
          type: string
        destination_address:
          $ref: '#/components/schemas/Address'
        destination_tag:
          type: number
        destination_amount:
          $ref: '#/components/schemas/Amount'
        invoice_id:
          type: string
        paths:
          type: string
        partial_payment:
          type: boolean
        no_direct_ripple:
          type: boolean
      required:
        - source_address
        - source_amount
        - destination_address
        - destination_amount
    Amount:
      description: An amount in the XRP Ledger.
      type: object
      properties:
        value:
          type: string
        currency:
          $ref: '#/components/schemas/Currency'
        issuer: # aka counterparty
          $ref: '#/components/schemas/Address'
      required:
        - value
        - currency
    Currency:
      type: string
      pattern: '^[0-9A-F]{40}$|^[A-Za-z0-9!@#$%^&*<>(){}\[\]\?|]{3}$|^drops$'
      example: 'USD'
      description: "A currency code that is valid in the XRP Ledger, or `XRP` for ledger's native currency."
      externalDocs:
        description: Currency codes in the XRP Ledger.
        url: 'https://developers.ripple.com/basic-data-types.html#currency-codes'
    Instructions:
      title: Transaction Instructions
      description: Indicates how to execute a transaction. Complements the transaction specification.
      type: object
      required:
      - sequence
      properties:
        fee:
          type: string
          description: An exact fee to pay for the transaction, in XRP.
        maxFee:
          type: string
          description: The maximum fee to pay for the transaction, in XRP.
        maxLedgerVersion:
          type: integer
          nullable: true
          description: The highest ledger version that the transaction can be included in.
        maxLedgerVersionOffset:
          type: integer
          description: Offset from the current validated ledger version to the highest ledger version that the transaction can be included in.
        sequence:
          type: integer
          description: The initiating account's sequence number for this transaction.
        signersCount:
          type: integer
          description: The number of signers that will be signing this transaction.

    TransactionStatus:
      title: TransactionStatus
      description: Transaction status returned immediately after submitting. If the transaction was submitted, `tx_json.hash` and `engine_result` will be included.
      type: object
      properties:
        engine_result:
          type: string
          description: Code indicating the preliminary result of the transaction, for example `tesSUCCESS`. Not final until included in a fully validated `TransactionResult`.
          externalDocs:
            description: List of transaction responses
            url: https://developers.ripple.com/transaction-results.html
        engine_result_code:
          type: integer
          description: Numeric code indicating the preliminary result of the transaction, directly correlated to `engine_result`.
        engine_result_message:
          type: string
          description: Human-readable explanation of the transaction's preliminary result.
        tx_blob:
          type: string
          description: The complete transaction in hex string format.
        tx_json:
          $ref: '#/components/schemas/TransactionCommonFields'
        accepted:
          type: boolean
          description: The value true indicates that the transaction was applied, queued, broadcast, or kept for later. The value false indicates that none of those happened, so the transaction cannot possibly succeed as long as you do not submit it again and have not already submitted it another time. (Requires rippled v1.5.0+)
        account_sequence_available:
          type: number
          description: The next Sequence Number available for the sending account after all pending and queued transactions.
        account_sequence_next:
          type: number
          description: The next Sequence Number for the sending account after all transactions that have been provisionally applied, but not transactions in the queue.
        applied:
          type: boolean
          description: The value true indicates that this transaction was applied to the open ledger. In this case, the transaction is likely, but not guaranteed, to be validated in the next ledger version.
        broadcast:
          type: boolean
          description: The value true indicates that this transaction was applied to the open ledger. In this case, the transaction is likely, but not guaranteed, to be validated in the next ledger version.
        kept:
          type: boolean
          description: The value true indicates that the transaction was kept to be retried later.
        queued:
          type: boolean
          description: The value true indicates the transaction was put in the Transaction Queue, which means it is likely to be included in a future ledger version.
        open_ledger_cost:
          type: string
          description: The current open ledger cost before processing this transaction. Transactions with a lower cost are likely to be queued.
        validated_ledger_index:
          type: integer
          description: The ledger index of the newest validated ledger at the time of submission. This provides a lower bound on the ledger versions that the transaction can appear in as a result of this request. (The transaction could only have been validated in this ledger version or earlier if it had already been submitted before.)

    TransactionCommonFields:
      title: Transaction Common Fields
      type: object
      description: The fields that are common to all transactions.
      required:
        - TransactionType
        - Account
        - Flags
        - LastLedgerSequence # could be optional, but we make the opinionated choice of requiring it
        - Fee
        - Sequence
      properties:
        hash:
          type: string
          description: (Optional) The hash value that uniquely identifies this transaction. Included only if the transaction was signed.

        TransactionType:
          type: string # TODO: enum of supported types
          description: The transaction type, such as "Payment".

        Account:
          # description: Source account of the transaction.
          $ref: '#/components/schemas/Address'

        Flags:
          type: integer
          format: int64
          description: Transaction-specific flags (bit field).
          example: 2147483648

        LastLedgerSequence:
          type: integer
          description: Highest ledger index this transaction can appear in. This field places a strict upper limit on how long the transaction can wait to be validated or rejected.
          externalDocs:
            description: Reliable Transaction Submission
            url: https://developers.ripple.com/reliable-transaction-submission.html

        Fee:
          type: string
          description: Transaction fee, in drops.

        Sequence:
          type: integer
          description: The account sequence number (can serve as a nonce).

    PaymentTransaction:
      allOf:
        - $ref: '#/components/schemas/TransactionCommonFields'
        - type: object
          required:
            - Destination
            - Amount
          properties:
            Destination:
              # description: Destination account to receive the payment.
              $ref: '#/components/schemas/Address'
            Amount:
              type: string
              description: The amount.

    SignedTransaction:
      title: Signed Transaction
      type: object
      description: A signed transaction.
      required:
        - signedTransaction
      properties:
        signedTransaction:
          type: string
          description: A signed transaction, represented as a hexadecimal string.

    ApiDoc:
      description: The requested apiDoc.
      type: object

  # Common Examples
  examples:
    paymentTransactionExample:
      value:
        TransactionType: "Payment"
        Account: "rNQao3Z1irwRjKWSs8heL4a8WKLPKfLrXs"
        Destination: "r4FNkJtbKvCTjcE4UaeAtgpHGf8mAbeCoL"
        Amount: "20000000"
        Flags: 2147483648
        LastLedgerSequence: 6279611
        Fee: "12"
        Sequence: 1
      summary: A sample XRPL payment transaction