THORChain Network API

openapi: 3.0.0
info:
  title: Thornode Auth Network API
  version: 3.19.1
  contact:
    email: devs@thorchain.org
  description: Thornode REST API.
tags:
- name: Network
paths:
  /v2/network:
    get:
      description: Returns an object containing Network data
      operationId: GetNetworkData
      responses:
        '200':
          $ref: '#/components/responses/NetworkResponse'
      summary: Network Data
      tags:
      - Network
  /thorchain/network:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    get:
      description: Returns network overview statistics.
      operationId: network
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkResponse'
  /thorchain/outbound_fees:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    get:
      description: Returns the last block information for all chains.
      operationId: outboundFees
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundFeesResponse'
  /thorchain/outbound_fee/{asset}:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    - $ref: '#/components/parameters/asset'
    get:
      description: Returns the outbound fee information for the provided asset.
      operationId: outboundFeeAsset
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutboundFeesResponse'
  /thorchain/inbound_addresses:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    get:
      description: Returns the set of asgard addresses that should be used for inbound transactions.
      operationId: inboundAddresses
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundAddressesResponse'
  /thorchain/lastblock:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    get:
      description: Returns the last block information for all chains.
      operationId: lastblock
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastBlockResponse'
  /thorchain/lastblock/{chain}:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    - $ref: '#/components/parameters/chain'
    get:
      description: Returns the last block information for the provided chain.
      operationId: lastblockChain
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastBlockResponse'
  /thorchain/version:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    get:
      description: Returns the network's current THORNode version, the network's next THORNode version, and the querier's THORNode version.
      operationId: version
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VersionResponse'
  /thorchain/upgrade_proposals:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    get:
      description: Returns the current upgrade proposals.
      operationId: upgradeProposals
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpgradeProposalsResponse'
  /thorchain/upgrade_proposal/{name}:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    - $ref: '#/components/parameters/name'
    get:
      description: Returns the upgrade proposal for the provided name.
      operationId: upgradeProposal
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpgradeProposalResponse'
  /thorchain/upgrade_votes/{name}:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    - $ref: '#/components/parameters/name'
    get:
      description: Returns the upgrade votes for the provided name.
      operationId: upgradeVotes
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpgradeVotesResponse'
  /thorchain/constants:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    get:
      description: Returns constant configuration, can be overridden by mimir.
      operationId: constants
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConstantsResponse'
  /thorchain/ragnarok:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    get:
      description: Returns a boolean indicating whether the chain is in ragnarok.
      operationId: ragnarok
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: boolean
                example: false
  /thorchain/ban/{address}:
    parameters:
    - $ref: '#/components/parameters/queryHeight'
    - $ref: '#/components/parameters/address'
    get:
      description: Returns the ban status for the provided node address.
      operationId: ban
      tags:
      - Network
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BanResponse'
components:
  responses:
    NetworkResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Network'
      description: Returns an object containing Network data
  schemas:
    BondMetrics:
      properties:
        averageActiveBond:
          description: Int64(e8), Average bond of active nodes
          type: string
        averageStandbyBond:
          description: Int64(e8), Average bond of standby nodes
          type: string
        bondHardCap:
          description: Int64(e8), Highest effective bond for nodes
          type: string
        maximumActiveBond:
          description: Int64(e8), Maxinum bond of active nodes
          type: string
        maximumStandbyBond:
          description: Int64(e8), Maximum bond of standby nodes
          type: string
        medianActiveBond:
          description: Int64(e8), Median bond of active nodes
          type: string
        medianStandbyBond:
          description: Int64(e8), Median bond of standby nodes
          type: string
        minimumActiveBond:
          description: Int64(e8), Minimum bond of active nodes
          type: string
        minimumStandbyBond:
          description: Int64(e8), Minimum bond of standby nodes
          type: string
        totalActiveBond:
          description: Int64(e8), Total bond of active nodes
          type: string
        totalStandbyBond:
          description: Int64(e8), Total bond of standby nodes
          type: string
      required:
      - totalActiveBond
      - averageActiveBond
      - medianActiveBond
      - minimumActiveBond
      - maximumActiveBond
      - bondHardCap
      - totalStandbyBond
      - averageStandbyBond
      - medianStandbyBond
      - minimumStandbyBond
      - maximumStandbyBond
      type: object
    BlockRewards:
      properties:
        blockReward:
          type: string
        bondReward:
          type: string
        poolReward:
          type: string
      required:
      - blockReward
      - bondReward
      - poolReward
      type: object
    Network:
      properties:
        activeBonds:
          description: 'Array of rune amounts (e8) bonded by each active node.

            '
          items:
            type: string
          type: array
        activeNodeCount:
          description: Int64, Number of active nodes
          type: string
        blockRewards:
          $ref: '#/components/schemas/BlockRewards'
        bondMetrics:
          $ref: '#/components/schemas/BondMetrics'
        bondingAPY:
          description: 'Float, E.g. 0.01 = 1%. Estimate of the compounded bonding earnings based on the current

            reserve size, emmission curve, blocks per year and pool share factor =

            (WeeklyBondIncome/BondAmount + 1)^52 - 1

            '
          type: string
        liquidityAPY:
          description: 'Float, E.g. 0.01 = 1%. Estimate of the compounded  liquidity provider earnings based

            on the current reserve size, emmission curve, blocks per year and pool share factor =

            (WeeklyLiquidityIncome/(totalPooledRune*2) + 1)^52 - 1

            '
          type: string
        nextChurnHeight:
          description: Int64, height (block number) of the next churn.
          type: string
        poolActivationCountdown:
          description: Int64, the remaining time of pool activation (in blocks)
          type: string
        poolShareFactor:
          description: 'Float [0..1], the ratio which is used to split earnings between liquidity provider and

            nodes.

            LPIncome = rewards * poolShareFactor ;

            BondIncome :=  rewards * (1 - poolShareFactor)

            '
          type: string
        standbyBonds:
          description: 'Array of rune amounts (e8) bonded by each standby node.

            '
          items:
            type: string
          type: array
        standbyNodeCount:
          description: 'Int64, Number of standby nodes, some of them might become active at the next churn.

            '
          type: string
        totalPooledRune:
          description: 'Int64(e8), total Rune in all pools. Because asset and Rune value is the same amount in

            every pool (by definition), the total amount pooled is totalPooledRune*2.

            '
          type: string
        totalReserve:
          description: Int64(e8), Current size of the Reserve.
          type: string
      required:
      - bondMetrics
      - blockRewards
      - activeBonds
      - standbyBonds
      - activeNodeCount
      - standbyNodeCount
      - totalPooledRune
      - totalReserve
      - nextChurnHeight
      - poolActivationCountdown
      - poolShareFactor
      - bondingAPY
      - liquidityAPY
      type: object
    UpgradeProposal:
      type: object
      required:
      - name
      - height
      - info
      properties:
        name:
          type: string
          example: scheduled upgrade 1
          description: the name of the upgrade
        height:
          type: integer
          format: int64
          example: 1234
          description: the block height at which the upgrade will occur
        info:
          type: string
          example: '{"binaries":{"linux/amd64":"https://link.to.binary.amd64","linux/arm64":"https://link.to.binary.arm64"}}'
          description: the description of the upgrade, typically json with URLs to binaries for use with automation tools
        approved:
          type: boolean
          example: true
          description: whether the upgrade has been approved by the active validators
        approved_percent:
          type: string
          example: '0.8'
          description: the percentage of active validators that have approved the upgrade
        validators_to_quorum:
          type: integer
          format: int64
          example: 20
          description: the amount of additional active validators required to reach quorum for the upgrade
        approvers:
          type: array
          items:
            type: string
            example: thor1f3s7q037eancht7sg0aj995dht25rwrnu4ats5
          description: the list of node addresses that have approved the upgrade
        rejecters:
          type: array
          items:
            type: string
            example: thor1f3s7q037eancht7sg0aj995dht25rwrnu4ats5
          description: the list of node addresses that have rejected the upgrade
    BanResponse:
      type: object
      properties:
        node_address:
          type: string
          example: thor1f3s7q037eancht7sg0aj995dht25rwrnu4ats5
        block_height:
          type: integer
          format: int64
        signers:
          type: array
          items:
            type: string
            example: thor1f3s7q037eancht7sg0aj995dht25rwrnu4ats5
    UpgradeProposalResponse:
      $ref: '#/components/schemas/UpgradeProposal'
    LastBlockResponse:
      type: array
      items:
        $ref: '#/components/schemas/LastBlock'
    UpgradeVotesResponse:
      type: array
      items:
        $ref: '#/components/schemas/UpgradeVote'
    UpgradeProposalsResponse:
      type: array
      items:
        $ref: '#/components/schemas/UpgradeProposal'
    ConstantsResponse:
      type: object
      properties:
        int_64_values:
          type: object
          additionalProperties:
            type: string
          example:
            AsgardSize: 40
        bool_values:
          type: object
          additionalProperties:
            type: string
          example:
            StrictBondLiquidityRatio: true
        string_values:
          type: object
          additionalProperties:
            type: string
          example:
            DefaultPoolStatus: Staged
    UpgradeVote:
      type: object
      required:
      - height
      - node_address
      - vote
      properties:
        node_address:
          type: string
          example: thor1f3s7q037eancht7sg0aj995dht25rwrnu4ats5
          description: the node address of the voter
        vote:
          type: string
          enum:
          - approve
          - reject
          example: approve
          description: the vote cast by the node
    VersionResponse:
      type: object
      required:
      - current
      - next
      - querier
      properties:
        current:
          type: string
          example: 0.17.0
          description: current version
        next:
          type: string
          example: 0.18.0
          description: next version (minimum version for a node to become Active)
        next_since_height:
          type: integer
          format: int64
          example: 2000000
          description: height at which the minimum joining version last changed
        querier:
          type: string
          example: 0.16.0
          description: querier version
    NetworkResponse:
      type: object
      required:
      - bond_reward_rune
      - total_bond_units
      - available_pools_rune
      - vaults_liquidity_rune
      - effective_security_bond
      - total_reserve
      - vaults_migrating
      - xmr_active_vault_ready
      - gas_spent_rune
      - gas_withheld_rune
      - native_outbound_fee_rune
      - native_tx_fee_rune
      - tns_register_fee_rune
      - tns_fee_per_block_rune
      - rune_price_in_tor
      - tor_price_in_rune
      - tor_price_halted
      properties:
        bond_reward_rune:
          type: string
          example: '857134475040'
          description: total amount of RUNE awarded to node operators
        total_bond_units:
          type: string
          example: '0'
          description: total bonded RUNE
        available_pools_rune:
          type: string
          example: '4785723312627752'
          description: RUNE in Available pools (equal in value to the Assets in those pools)
        vaults_liquidity_rune:
          type: string
          example: '5792105087034476'
          description: RUNE value of Layer 1 Assets in vaults
        effective_security_bond:
          type: string
          example: '0'
          description: effective security bond used to determine maximum pooled RUNE
        total_reserve:
          type: string
          example: '21999180112172346'
          description: total reserve RUNE
        vaults_migrating:
          type: boolean
          example: false
          description: Returns true if there exist RetiringVaults which have not finished migrating funds to new ActiveVaults
        xmr_active_vault_ready:
          type: boolean
          example: false
          description: Indicates whether an active Asgard vault currently has spendable XMR funds
        gas_spent_rune:
          type: string
          example: '1000000000'
          description: Sum of the gas the network has spent to send outbounds
        gas_withheld_rune:
          type: string
          example: '1500000000'
          description: Sum of the gas withheld from users to cover outbound gas
        outbound_fee_multiplier:
          type: string
          example: '15000'
          description: Current outbound fee multiplier, in basis points
        native_outbound_fee_rune:
          type: string
          example: '100000000'
          description: the outbound transaction fee in rune, converted from the NativeOutboundFeeUSD mimir (after USD fees are enabled)
        native_tx_fee_rune:
          type: string
          example: '100000000'
          description: the native transaction fee in rune, converted from the NativeTransactionFeeUSD mimir (after USD fees are enabled)
        tns_register_fee_rune:
          type: string
          example: '1000000000'
          description: the thorname register fee in rune, converted from the TNSRegisterFeeUSD mimir (after USD fees are enabled)
        tns_fee_per_block_rune:
          type: string
          example: '20'
          description: the thorname fee per block in rune, converted from the TNSFeePerBlockUSD mimir (after USD fees are enabled)
        rune_price_in_tor:
          type: string
          example: '10'
          description: the rune price in tor
        tor_price_in_rune:
          type: string
          example: '10'
          description: the tor price in rune
        tor_price_halted:
          type: boolean
          example: false
          description: indicates if all anchor chains are halted (true), or at least one anchor chain is available (false)
    LastBlock:
      type: object
      required:
      - chain
      - last_observed_in
      - last_signed_out
      - thorchain
      properties:
        chain:
          type: string
        last_observed_in:
          type: integer
          format: int64
        last_signed_out:
          type: integer
          format: int64
        thorchain:
          type: integer
          format: int64
    InboundAddressesResponse:
      type: array
      items:
        $ref: '#/components/schemas/InboundAddress'
    OutboundFee:
      type: object
      required:
      - asset
      - outbound_fee
      properties:
        asset:
          type: string
          example: ETH.ETH
          description: the asset to display the outbound fee for
        outbound_fee:
          type: string
          example: '300000'
          description: the asset's outbound fee, in (1e8-format) units of the asset
        fee_withheld_rune:
          type: string
          example: '30000000000000'
          description: Total RUNE the network has withheld as fees to later cover gas costs for this asset's outbounds
        fee_spent_rune:
          type: string
          example: '20000000000000'
          description: Total RUNE the network has spent to reimburse gas costs for this asset's outbounds
        surplus_rune:
          type: string
          example: '10000000000000'
          description: amount of RUNE by which the fee_withheld_rune exceeds the fee_spent_rune
        dynamic_multiplier_basis_points:
          type: string
          example: '15000'
          description: dynamic multiplier basis points, based on the surplus_rune, affecting the size of the outbound_fee
    OutboundFeesResponse:
      type: array
      items:
        $ref: '#/components/schemas/OutboundFee'
    InboundAddress:
      type: object
      required:
      - halted
      - global_trading_paused
      - chain_trading_paused
      - chain_lp_actions_paused
      properties:
        chain:
          type: string
          example: BTC
        pub_key:
          type: string
          example: thorpub1addwnpepq2jqhv5rdqlkusfxy05stfzcgslhhz5qh8pxetw5ry2aa6awgdh3shq8s82
        address:
          type: string
          example: bc1qn9esxuw8ca7ts8l6w66kdh800s09msvutydc46
        router:
          type: string
          example: '0xD37BbE5744D730a1d98d8DC97c42F0Ca46aD7146'
        halted:
          type: boolean
          example: false
          description: Returns true if trading is unavailable for this chain, either because trading is halted globally or specifically for this chain
        global_trading_paused:
          type: boolean
          example: false
          description: Returns true if trading is paused globally
        chain_trading_paused:
          type: boolean
          example: false
          description: Returns true if trading is paused for this chain
        chain_lp_actions_paused:
          type: boolean
          example: false
          description: Returns true if LP actions are paused for this chain
        observed_fee_rate:
          type: string
          example: '114'
          description: The chain's observed fee rate in 1e8 format, before the 1.5x that makes an outbound more likely to have a sufficient gas rate.  Used by validators to check whether they need to report a fee change.
        gas_rate:
          type: string
          example: '216'
          description: The minimum fee rate used by vaults to send outbound TXs. The actual fee rate may be higher. For EVM chains this is returned in gwei (1e9).
        gas_rate_units:
          type: string
          example: satsperbyte
          description: Units of the gas_rate.
        outbound_tx_size:
          type: string
          example: '1000'
          description: Avg size of outbound TXs on each chain. For UTXO chains it may be larger than average, as it takes into account vault consolidation txs, which can have many vouts
        outbound_fee:
          type: string
          example: '216000'
          description: The total outbound fee charged to the user for outbound txs in the gas asset of the chain.  Can be observed_fee_rate * 1.5 * outbound_tx_size or else kept to an equivalent of Mimir key MinimumL1OutboundFeeUSD.
        dust_threshold:
          type: string
          example: '10000'
          description: Defines the minimum transaction size for the chain in base units (sats, wei, uatom). Transactions with asset amounts lower than the dust_threshold are ignored.
  parameters:
    address:
      name: address
      in: path
      required: true
      schema:
        type: string
        example: thor1zupk5lmc84r2dh738a9g3zscavannjy3nzplwt
    queryHeight:
      name: height
      in: query
      description: optional block height, defaults to current tip
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
    chain:
      name: chain
      in: path
      required: true
      schema:
        type: string
        example: BTC
    name:
      name: name
      in: path
      required: true
      schema:
        type: string
        example: v3.137.0
    asset:
      name: asset
      in: path
      required: true
      schema:
        type: string
        example: BTC.BTC