Midgard Public API (2.20.1)

Download OpenAPI specification:Download

The Midgard Public API queries THORChain and any chains linked via the Bifröst and prepares information about the network to be readily available for public users. The API parses transaction event data from THORChain and stores them in a time-series database to make time-dependent queries easy. Midgard does not hold critical information. To interact with THORChain protocol, users should query THORNode directly.

Specification

Documentation

Swagger/OpenAPI 3.0 specification generated documents.

Responses

Swagger File

Returns human and machine readable swagger/openapi specification

Responses

Health Info

Returns an object containing the health response of the API. Meaning of heights:

lastThorNode - Latest block as reported by ThorNode.

lastFetched - Latest block fetched from ThorNode.

lastCommitted - Latest block committed to the DB but not fully processed yet.

lastAggregated - Latest block fully processed and aggregated.

genesisInfo - The genesis height Midgard bootstrapped with.

Responses

Response samples

Content type
application/json
{
  • "database": true,
  • "scannerHeight": "string",
  • "inSync": true,
  • "lastThorNode": {
    },
  • "lastFetched": {
    },
  • "lastCommitted": {
    },
  • "lastAggregated": {
    },
  • "genesisInfo": {
    }
}

Churns List

Returns block height and timestamp for each churn.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Known Pools List

Returns an object with known pools and their statuses

Responses

Response samples

Content type
application/json
{
  • "BTC.BTC": "available"
}

Pools List

Returns an array containing details for a set of pools

query Parameters
status
string
Enum: "available" "staged" "suspended"

Filter for only pools with this status

period
string
Enum: "1h" "24h" "7d" "14d" "30d" "90d" "100d" "180d" "365d" "all"
Example: period=100d

Specifies the base interval from which annualPercentageRate and poolAPY is extrapolated. Default is 14d.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Details of a Pool

Returns details of the pool: depths, price, 24h volume, APY.

path Parameters
asset
required
string
Example: BNB.TOMOB-1E1

pool name

query Parameters
period
string
Enum: "1h" "24h" "7d" "14d" "30d" "90d" "100d" "180d" "365d" "all"
Example: period=100d

Specifies the base interval from which APY is extrapolated. Default is 14d.

Responses

Response samples

Content type
application/json
{
  • "asset": "string",
  • "volume24h": "string",
  • "assetDepth": "string",
  • "runeDepth": "string",
  • "assetPrice": "string",
  • "assetPriceUSD": "string",
  • "poolAPY": "string",
  • "annualPercentageRate": "string",
  • "earnings": "string",
  • "earningsAnnualAsPercentOfDepth": "string",
  • "lpLuvi": "string",
  • "saversAPR": "string",
  • "status": "string",
  • "liquidityUnits": "string",
  • "synthUnits": "string",
  • "synthSupply": "string",
  • "units": "string",
  • "nativeDecimal": "string",
  • "saversUnits": "string",
  • "saversDepth": "string",
  • "totalCollateral": "string",
  • "totalDebtTor": "string"
}

Pool Statistics

Statistics about the pool. The description of the fields have pointers about the corresponding v2/history location. Visit the history endpoint for drilldowns.

path Parameters
asset
required
string
Example: BNB.TOMOB-1E1

pool name

query Parameters
period
string
Enum: "1h" "24h" "7d" "14d" "30d" "90d" "100d" "180d" "365d" "all"
Example: period=24h

Restricts aggregation type fields to the last period only. Default is 14d.

Responses

Response samples

Content type
application/json
{
  • "asset": "string",
  • "status": "string",
  • "assetPrice": "string",
  • "assetPriceUSD": "string",
  • "assetDepth": "string",
  • "runeDepth": "string",
  • "synthUnits": "string",
  • "synthSupply": "string",
  • "liquidityUnits": "string",
  • "units": "string",
  • "toAssetVolume": "string",
  • "toRuneVolume": "string",
  • "swapVolume": "string",
  • "toAssetCount": "string",
  • "toRuneCount": "string",
  • "swapCount": "string",
  • "uniqueSwapperCount": "string",
  • "toAssetAverageSlip": "string",
  • "toRuneAverageSlip": "string",
  • "averageSlip": "string",
  • "toAssetFees": "string",
  • "toRuneFees": "string",
  • "totalFees": "string",
  • "poolAPY": "string",
  • "annualPercentageRate": "string",
  • "saversAPR": "string",
  • "earnings": "string",
  • "earningsAnnualAsPercentOfDepth": "string",
  • "addAssetLiquidityVolume": "string",
  • "addRuneLiquidityVolume": "string",
  • "addLiquidityVolume": "string",
  • "addLiquidityCount": "string",
  • "withdrawAssetVolume": "string",
  • "withdrawRuneVolume": "string",
  • "withdrawVolume": "string",
  • "withdrawCount": "string",
  • "uniqueMemberCount": "string"
}

Depth and Price History

Returns the asset and rune depths and price. The values report the state at the end of each interval.

History endpoint has two modes:

  • With Interval parameter it returns a series of time buckets. From and To dates will be rounded to the Interval boundaries.

  • Without Interval parameter a single From..To search is performed with exact timestamps.

  • Interval: possible values: 5min, hour, day, week, month, quarter, year.

  • count: [1..400]. Defines number of intervals. Don't provide if Interval is missing.

  • from/to: optional int, unix second.

Possible usages with interval.

  • last 10 days: ?interval=day&count=10
  • last 10 days before to: ?interval=day&count=10&to=1608825600
  • next 10 days after from: ?interval=day&count=10&from=1606780800
  • Days between from and to. From defaults to start of chain, to defaults to now. Only the first 400 intervals are returned: interval=day&from=1606780800&to=1608825600

Pagination is possible with from&count and then using the returned meta.endTime as the From parameter of the next query.

Possible configurations without interval:

  • exact search for one time frame: ?from=1606780899&to=1608825600
  • one time frame until now: ?from=1606780899
  • from chain start until now: no query parameters
path Parameters
pool
required
string

Return stats for this single pool.

query Parameters
interval
string
Enum: "5min" "hour" "day" "week" "month" "quarter" "year"
Example: interval=day

Interval of calculations

count
integer
Example: count=30

Number of intervals to return. Should be between [1..400].

to
integer <int64>
Example: to=1608825600

End time of the query as unix timestamp. If only count is given, defaults to now.

from
integer <int64>
Example: from=1606780800

Start time of the query as unix timestamp

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "intervals": [
    ]
}

Savers Units and Depth History

Returns savers depths and units. The values report the state at the end of each interval.

History endpoint has two modes:

  • With Interval parameter it returns a series of time buckets. From and To dates will be rounded to the Interval boundaries.

  • Without Interval parameter a single From..To search is performed with exact timestamps.

  • Interval: possible values: 5min, hour, day, week, month, quarter, year.

  • count: [1..400]. Defines number of intervals. Don't provide if Interval is missing.

  • from/to: optional int, unix second.

Possible usages with interval.

  • last 10 days: ?interval=day&count=10
  • last 10 days before to: ?interval=day&count=10&to=1608825600
  • next 10 days after from: ?interval=day&count=10&from=1606780800
  • Days between from and to. From defaults to start of chain, to defaults to now. Only the first 400 intervals are returned: interval=day&from=1606780800&to=1608825600

Pagination is possible with from&count and then using the returned meta.endTime as the From parameter of the next query.

Possible configurations without interval:

  • exact search for one time frame: ?from=1606780899&to=1608825600
  • one time frame until now: ?from=1606780899
  • from chain start until now: no query parameters
path Parameters
pool
required
string

Return stats for this single pool.

query Parameters
interval
string
Enum: "5min" "hour" "day" "week" "month" "quarter" "year"
Example: interval=day

Interval of calculations

count
integer
Example: count=30

Number of intervals to return. Should be between [1..400].

to
integer <int64>
Example: to=1608825600

End time of the query as unix timestamp. If only count is given, defaults to now.

from
integer <int64>
Example: from=1606780800

Start time of the query as unix timestamp

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "intervals": [
    ]
}

Earnings History

Returns earnings data for the specified interval.

History endpoint has two modes:

  • With Interval parameter it returns a series of time buckets. From and To dates will be rounded to the Interval boundaries.

  • Without Interval parameter a single From..To search is performed with exact timestamps.

  • Interval: possible values: 5min, hour, day, week, month, quarter, year.

  • count: [1..400]. Defines number of intervals. Don't provide if Interval is missing.

  • from/to: optional int, unix second.

Possible usages with interval.

  • last 10 days: ?interval=day&count=10
  • last 10 days before to: ?interval=day&count=10&to=1608825600
  • next 10 days after from: ?interval=day&count=10&from=1606780800
  • Days between from and to. From defaults to start of chain, to defaults to now. Only the first 400 intervals are returned: interval=day&from=1606780800&to=1608825600

Pagination is possible with from&count and then using the returned meta.endTime as the From parameter of the next query.

Possible configurations without interval:

  • exact search for one time frame: ?from=1606780899&to=1608825600
  • one time frame until now: ?from=1606780899
  • from chain start until now: no query parameters
query Parameters
interval
string
Enum: "5min" "hour" "day" "week" "month" "quarter" "year"
Example: interval=day

Interval of calculations

count
integer
Example: count=30

Number of intervals to return. Should be between [1..400].

to
integer <int64>
Example: to=1608825600

End time of the query as unix timestamp. If only count is given, defaults to now.

from
integer <int64>
Example: from=1606780800

Start time of the query as unix timestamp

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "intervals": [
    ]
}

Swaps History

Returns swap count, volume, fees, slip in specified interval. If pool is not specified returns for all pools

History endpoint has two modes:

  • With Interval parameter it returns a series of time buckets. From and To dates will be rounded to the Interval boundaries.

  • Without Interval parameter a single From..To search is performed with exact timestamps.

  • Interval: possible values: 5min, hour, day, week, month, quarter, year.

  • count: [1..400]. Defines number of intervals. Don't provide if Interval is missing.

  • from/to: optional int, unix second.

Possible usages with interval.

  • last 10 days: ?interval=day&count=10
  • last 10 days before to: ?interval=day&count=10&to=1608825600
  • next 10 days after from: ?interval=day&count=10&from=1606780800
  • Days between from and to. From defaults to start of chain, to defaults to now. Only the first 400 intervals are returned: interval=day&from=1606780800&to=1608825600

Pagination is possible with from&count and then using the returned meta.endTime as the From parameter of the next query.

Possible configurations without interval:

  • exact search for one time frame: ?from=1606780899&to=1608825600
  • one time frame until now: ?from=1606780899
  • from chain start until now: no query parameters
query Parameters
pool
string

Return history given pool. Returns sum of all pools if missing.

interval
string
Enum: "5min" "hour" "day" "week" "month" "quarter" "year"
Example: interval=day

Interval of calculations

count
integer
Example: count=30

Number of intervals to return. Should be between [1..400].

to
integer <int64>
Example: to=1608825600

End time of the query as unix timestamp. If only count is given, defaults to now.

from
integer <int64>
Example: from=1606780800

Start time of the query as unix timestamp

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "intervals": [
    ]
}

Total Value Locked History

Returns total pool depths, total bonds, and total value locked in specified interval.

Total Value Locked = Total Bonds + 2 * Total Pool Depths

History endpoint has two modes:

  • With Interval parameter it returns a series of time buckets. From and To dates will be rounded to the Interval boundaries.

  • Without Interval parameter a single From..To search is performed with exact timestamps.

  • Interval: possible values: 5min, hour, day, week, month, quarter, year.

  • count: [1..400]. Defines number of intervals. Don't provide if Interval is missing.

  • from/to: optional int, unix second.

Possible usages with interval.

  • last 10 days: ?interval=day&count=10
  • last 10 days before to: ?interval=day&count=10&to=1608825600
  • next 10 days after from: ?interval=day&count=10&from=1606780800
  • Days between from and to. From defaults to start of chain, to defaults to now. Only the first 400 intervals are returned: interval=day&from=1606780800&to=1608825600

Pagination is possible with from&count and then using the returned meta.endTime as the From parameter of the next query.

Possible configurations without interval:

  • exact search for one time frame: ?from=1606780899&to=1608825600
  • one time frame until now: ?from=1606780899
  • from chain start until now: no query parameters
query Parameters
interval
string
Enum: "5min" "hour" "day" "week" "month" "quarter" "year"
Example: interval=day

Interval of calculations

count
integer
Example: count=30

Number of intervals to return. Should be between [1..400].

to
integer <int64>
Example: to=1608825600

End time of the query as unix timestamp. If only count is given, defaults to now.

from
integer <int64>
Example: from=1606780800

Start time of the query as unix timestamp

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "intervals": [
    ]
}

Liquidity Changes History

Returns withdrawals and deposits for given time interval. If pool is not specified returns for all pools

History endpoint has two modes:

  • With Interval parameter it returns a series of time buckets. From and To dates will be rounded to the Interval boundaries.

  • Without Interval parameter a single From..To search is performed with exact timestamps.

  • Interval: possible values: 5min, hour, day, week, month, quarter, year.

  • count: [1..400]. Defines number of intervals. Don't provide if Interval is missing.

  • from/to: optional int, unix second.

Possible usages with interval.

  • last 10 days: ?interval=day&count=10
  • last 10 days before to: ?interval=day&count=10&to=1608825600
  • next 10 days after from: ?interval=day&count=10&from=1606780800
  • Days between from and to. From defaults to start of chain, to defaults to now. Only the first 400 intervals are returned: interval=day&from=1606780800&to=1608825600

Pagination is possible with from&count and then using the returned meta.endTime as the From parameter of the next query.

Possible configurations without interval:

  • exact search for one time frame: ?from=1606780899&to=1608825600
  • one time frame until now: ?from=1606780899
  • from chain start until now: no query parameters
query Parameters
pool
string

Return stats for given pool. Returns sum of all pools if missing

interval
string
Enum: "5min" "hour" "day" "week" "month" "quarter" "year"
Example: interval=day

Interval of calculations

count
integer
Example: count=30

Number of intervals to return. Should be between [1..400]

to
integer <int64>
Example: to=1608825600

End time of the query as unix timestamp. If only count is given, defaults to now

from
integer <int64>
Example: from=1606780800

Start time of the query as unix timestamp

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "intervals": [
    ]
}

Nodes List

Returns a list of Node public keys and adresses.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Network Data

Returns an object containing Network data

Responses

Response samples

Content type
application/json
{
  • "bondMetrics": {
    },
  • "blockRewards": {
    },
  • "activeBonds": [
    ],
  • "standbyBonds": [
    ],
  • "activeNodeCount": "string",
  • "standbyNodeCount": "string",
  • "totalPooledRune": "string",
  • "totalReserve": "string",
  • "nextChurnHeight": "string",
  • "poolActivationCountdown": "string",
  • "poolShareFactor": "string",
  • "bondingAPY": "string",
  • "liquidityAPY": "string"
}

Actions List

List actions along with their related transactions. An action is generated by one or more inbound transactions with the intended action set in the transaction memo. The action may result in one or more outbound transactions. Results are paginated by sets of 50. Filters may be applied to query actions.

query Parameters
address
string
Example: address=tbnb1fj2lqj8dvr5pumfchc7ntlfqd2v6zdxqwjewf5

Comma separated list. Address of sender or recipient of any in/out transaction related to the action.

txid
string
Example: txid=2F624637DE179665BA3322B864DB9F30001FD37B4E0D22A0B6ECE6A5B078DAB4

ID of any in/out tx related to the action

asset
string
Examples:
  • asset=BTC.BTC,THOR.RUNE - Regular multiple asset query. (having at least either one of them)
  • asset=nosynth,norune - Query action that are neither synth nor rune asset

Comma separated list. Any asset that is part of the action (CHAIN.SYMBOL) Additionally, synth, nosynth, and norune filters can be used for swap, add/withdraw actions.

type
string
Example: type=swap,addLiquidity

One or more comma separated unique types of action (swap, addLiquidity, withdraw, donate, refund, switch)

affiliate
string
Examples:
  • affiliate=thor102y0m3uptg0vvudeyh00r2fnz70wq7d8y7mu2g -
  • affiliate=ts,thor102y0m3uptg0vvudeyh00r2fnz70wq7d8y7mu2g - Query affiliates that one is THORName and other is address

Comma separated list. Affiliate address of the action (swap, refund)

limit
integer <int64> [ 0 .. 50 ]

number of actions returned, default is 50

offset
integer <int64> >= 0

pagination offset, default is 0

nextPageToken
integer <int64> >= 0

if this is given, the actions for the next page will be given

timestamp
integer <int64> >= 0

if this is given, the actions older than the timestamp will be given

height
integer <int64> >= 0

if this is given, the actions older than the height will be given

prevPageToken
integer <int64> >= 0

if this is given, the actions for the previous page will be given

fromTimestamp
integer <int64> >= 0

if this is given, the actions newer than the timestamp will be given

fromHeight
integer <int64> >= 0

if this is given, the actions newer than the height will be given

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "count": "string",
  • "actions": [
    ]
}

Members List

Returns an array containing the addresses for all pool members. Addresses are only shown once. If there's both a RUNE address and an asset address for a member, only the RUNE address will be shown.

query Parameters
pool
string

Return only members present in the pool.

Responses

Response samples

Content type
application/json
[
  • "tbnb1fj2lqj8dvr5pumfchc7ntlfqd2v6zdxqwjewf5"
]

Member Details

Returns an array of statistics for all the liquidity providers associated with a given member address.

path Parameters
address
required
string
Example: bnb1jxfh2g85q3v0tdq56fnevx6xcxtcnhtsmcu64m,bc1qcxssye4j6730h7ehgega3gyykkuwgdgmmpu62n

Address to match liquidity providers. Either a rune or an asset address may be given. Query can also be multiple addresses should be seperated by comma (',')

query Parameters
showSavers
boolean
Default: false
Example: showSavers=true

A flag to show saver vault membership details, the default is false.

Responses

Response samples

Content type
application/json
{
  • "pools": [
    ]
}

Borrowers List

Returns an array containing the addresses for all borrowers. Addresses are only shown once.

query Parameters
asset
string

Return only borrowers getting loan against this asset as collateral.

Responses

Response samples

Content type
application/json
[
  • "tbnb1fj2lqj8dvr5pumfchc7ntlfqd2v6zdxqwjewf5"
]

Borrower Details

Returns an array of statistics for all the open loans associated with a given borrower address.

path Parameters
address
required
string
Example: bnb1jxfh2g85q3v0tdq56fnevx6xcxtcnhtsmcu64m,bc1qcxssye4j6730h7ehgega3gyykkuwgdgmmpu62n

Address to match borrower, an asset address is given. Query can also be multiple addresses should be seperated by comma (',')

Responses

Response samples

Content type
application/json
{
  • "pools": [
    ]
}

Saver Details

Returns an array of statistics for all the savers associated with a given member address. Query can also be multiple addresses should be seperated by comma (',')

path Parameters
address
required
string
Example: bnb1jxfh2g85q3v0tdq56fnevx6xcxtcnhtsmcu64m,bc1qcxssye4j6730h7ehgega3gyykkuwgdgmmpu62n

Address to match the saver. an asset address should be given.

Responses

Response samples

Content type
application/json
{
  • "pools": [
    ]
}

THORName Details

Returns an array of chains and their addresses associated with the given THORName

path Parameters
name
required
string
Example: thorchain

a THORName

Responses

Response samples

Content type
application/json
{
  • "owner": "thor102y0m3uptg0vvudeyh00r2fnz70wq7d8y7mu2g",
  • "expire": "string",
  • "entries": [
    ]
}

Gives a list of THORNames by reverse lookup

Returns an array of THORNames associated with the given address

path Parameters
address
required
string
Example: bnb1jxfh2g85q3v0tdq56fnevx6xcxtcnhtsmcu64m

Address to match THORNames against.

Responses

Response samples

Content type
application/json
[
  • "myname"
]

THORName owner

Returns an array of THORNames owned by the address. The address is not necessarily an associated address for those thornames.

path Parameters
address
required
string
Example: thor102y0m3uptg0vvudeyh00r2fnz70wq7d8y7mu2g

Address which owns a THORName.

Responses

Response samples

Content type
application/json
[
  • "myname"
]

Global Stats

Returns an object containing global stats for all pools and all transactions

Responses

Response samples

Content type
application/json
{
  • "runeDepth": "string",
  • "switchedRune": "string",
  • "runePriceUSD": "string",
  • "swapVolume": "string",
  • "swapCount24h": "string",
  • "swapCount30d": "string",
  • "swapCount": "string",
  • "toAssetCount": "string",
  • "toRuneCount": "string",
  • "synthMintCount": "string",
  • "synthBurnCount": "string",
  • "dailyActiveUsers": "string",
  • "monthlyActiveUsers": "string",
  • "uniqueSwapperCount": "string",
  • "addLiquidityVolume": "string",
  • "withdrawVolume": "string",
  • "addLiquidityCount": "string",
  • "withdrawCount": "string"
}

Current balance for an address

Returns all coin amounts of the given address at the specified timestamp or height, or at the latest process block if neither is provided. (Only one of timestamp or height can be specified, not both.)

This endpoint is enabled only if the midgard startup config allows it.

path Parameters
address
required
string
Example: thor102y0m3uptg0vvudeyh00r2fnz70wq7d8y7mu2g

Rune address.

query Parameters
timestamp
integer <int64>
Example: timestamp=1606780800

Unix timestamp as seconds since 1970 (if provided, height must not be provided)

height
integer <int64>
Example: height=2000000

Block height (if provided, timestamp must not be provided)

Responses

Response samples

Content type
application/json
{
  • "height": "2000000",
  • "date": "946684801000000000",
  • "coins": [
    ]
}