Address Ocean REST API

With the Address API, you can query address related resources such as UTXO balances, Token Balances, Vaults and Transactions.

Balance

Get current UTXO balance of an address.

Code Samples

Shell

curl https://ocean.defichain.com/v0/mainnet/address/8defichainBurnAddressXXXXXXXdRQkSm/balance

JavaScript (@defichain/whale-api-client)

await api.address.getBalance('8defichainBurnAddressXXXXXXXdRQkSm')

Response

{
  "data": "156001771.37400823"
}

Aggregation

Get current aggregated stats of an address.

Code Samples

Shell

curl https://ocean.defichain.com/v0/mainnet/address/8defichainBurnAddressXXXXXXXdRQkSm/aggregation

JavaScript (@defichain/whale-api-client)

await api.address.getAggregation('8defichainBurnAddressXXXXXXXdRQkSm')

Response

{
  "data": {
    "id": "0014dd65e70680db7f28c22b9ef50a72b923e8991488a50f8b104022d92c42ebad7ee175",
    "hid": "e70680db7f28c22b9ef50a72b923e8991488a50f8b104022d92c42ebad7ee175",
    "block": {
      "hash": "2569c94596faff8337a0f0c9acec58fa745031d904aa435d918a9a8fc71ec3c7",
      "height": 1367397,
      "time": 1636979762,
      "medianTime": 1636979644
    },
    "script": {
      "type": "pubkeyhash",
      "hex": "76a914f7874e8821097615ec345f74c7e5bcf61b12e2ee88ac"
    },
    "statistic": {
      "txCount": 70,
      "txInCount": 70,
      "txOutCount": 0
    },
    "amount": {
      "txIn": "156001771.37400823",
      "txOut": "0.00000000",
      "unspent": "156001771.37400823"
    }
  }
}

TypeScript Definitions

export interface AddressAggregation {
  id: string
  hid: string

  block: {
    hash: string
    height: number
    time: number
    medianTime: number
  }

  script: {
    type: string
    hex: string
  }

  statistic: {
    txCount: number
    txInCount: number
    txOutCount: number
  }

  amount: {
    txIn: string
    txOut: string
    unspent: string
  }
}

Token Balances

List all tokens balance belonging to an address.

Code Samples

Shell

curl https://ocean.defichain.com/v0/mainnet/address/8defichainBurnAddressXXXXXXXdRQkSm/tokens

JavaScript (@defichain/whale-api-client)

await api.address.listToken('8defichainBurnAddressXXXXXXXdRQkSm')

Response

{
  "data": [
    {
      "id": "0",
      "amount": "190420.61840602",
      "symbol": "DFI",
      "symbolKey": "DFI",
      "name": "Default Defi token",
      "isDAT": true,
      "isLPS": false,
      "isLoanToken": false,
      "displaySymbol": "DFI"
    }
  ]
}

TypeScript Definitions

export interface AddressToken {
  id: string
  amount: string
  symbol: string
  displaySymbol: string
  symbolKey: string
  name: string
  isDAT: boolean
  isLPS: boolean
  isLoanToken: boolean
}

Vault

List all vaults belonging to an address.

Code Samples

Shell

curl https://ocean.defichain.com/v0/mainnet/address/8defichainBurnAddressXXXXXXXdRQkSm/vaults

JavaScript (@defichain/whale-api-client)

await api.address.listVault('8defichainBurnAddressXXXXXXXdRQkSm')

Response

{
  "data": [
    {
      "vaultId": "ea4434f9b3f360797d4727fe71fe74f06b2bf6d238fc62244d10290519603c00",
      "loanScheme": {
        "id": "MIN150",
        "minColRatio": "150",
        "interestRate": "5"
      },
      "ownerAddress": "df1qhwe39k0nyl3ttjqu3przvhqx6kaudmn8snjdpw",
      "state": "ACTIVE",
      "informativeRatio": "246.3901291",
      "collateralRatio": "246",
      "collateralValue": "5940.37668673",
      "loanValue": "2410.96374611",
      "interestValue": "3.68958982",
      "collateralAmounts": [
        {
          "id": "0",
          "amount": "792.01490190",
          "symbol": "DFI",
          "symbolKey": "DFI",
          "name": "Default Defi token",
          "displaySymbol": "DFI",
          "activePrice": {
            "id": "DFI-USD-1546440",
            "key": "DFI-USD",
            "isLive": true,
            "block": {
              "hash": "5e177f763f271e57b07f11c981875ec6e60f46f86dda8e1e441e4e07a9163e0f",
              "height": 1546440,
              "medianTime": 1642444068,
              "time": 1642444092
            },
            "active": {
              "amount": "3.05197409",
              "weightage": 30,
              "oracles": {
                "active": 3,
                "total": 3
              }
            },
            "next": {
              "amount": "3.04095913",
              "weightage": 30,
              "oracles": {
                "active": 3,
                "total": 3
              }
            },
            "sort": "001798c8"
          }
        },
        {
          "id": "2",
          "amount": "0.08343110",
          "symbol": "BTC",
          "symbolKey": "BTC",
          "name": "Bitcoin",
          "displaySymbol": "dBTC",
          "activePrice": {
            "id": "BTC-USD-1546440",
            "key": "BTC-USD",
            "isLive": true,
            "block": {
              "hash": "5e177f763f271e57b07f11c981875ec6e60f46f86dda8e1e441e4e07a9163e0f",
              "height": 1546440,
              "medianTime": 1642444068,
              "time": 1642444092
            },
            "active": {
              "amount": "42228.47028558",
              "weightage": 30,
              "oracles": {
                "active": 3,
                "total": 3
              }
            },
            "next": {
              "amount": "42049.79165569",
              "weightage": 30,
              "oracles": {
                "active": 3,
                "total": 3
              }
            },
            "sort": "001798c8"
          }
        }
      ],
      "loanAmounts": [
        {
          "id": "15",
          "amount": "2410.96374611",
          "symbol": "DUSD",
          "symbolKey": "DUSD",
          "name": "Decentralized USD",
          "displaySymbol": "DUSD"
        }
      ],
      "interestAmounts": [
        {
          "id": "15",
          "amount": "3.68958982",
          "symbol": "DUSD",
          "symbolKey": "DUSD",
          "name": "Decentralized USD",
          "displaySymbol": "DUSD"
        }
      ]
    }
  ]
}

TypeScript Definitions

export interface LoanVaultActive {
  vaultId: string
  loanScheme: LoanScheme
  ownerAddress: string
  state: LoanVaultState.ACTIVE | LoanVaultState.FROZEN | LoanVaultState.MAY_LIQUIDATE | LoanVaultState.UNKNOWN

  informativeRatio: string
  collateralRatio: string
  collateralValue: string
  loanValue: string
  interestValue: string

  collateralAmounts: LoanVaultTokenAmount[]
  loanAmounts: LoanVaultTokenAmount[]
  interestAmounts: LoanVaultTokenAmount[]
}

export interface LoanVaultLiquidated {
  vaultId: string
  loanScheme: LoanScheme
  ownerAddress: string
  state: LoanVaultState.IN_LIQUIDATION

  liquidationHeight: number
  liquidationPenalty: number
  batchCount: number
  batches: LoanVaultLiquidationBatch[]
}

export interface LoanScheme {
  id: string
  minColRatio: string
  interestRate: string
}

export interface LoanVaultLiquidationBatch {
  index: number
  collaterals: LoanVaultTokenAmount[]
  loan: LoanVaultTokenAmount
  highestBid?: HighestBid
}

export enum LoanVaultState {
  UNKNOWN = 'UNKNOWN',
  ACTIVE = 'ACTIVE',
  FROZEN = 'FROZEN',
  IN_LIQUIDATION = 'IN_LIQUIDATION',
  MAY_LIQUIDATE = 'MAY_LIQUIDATE'
}

export interface LoanVaultTokenAmount {
  id: string
  amount: string
  symbol: string
  displaySymbol: string
  symbolKey: string
  name: string
  activePrice?: ActivePrice
}

export interface HighestBid {
  owner: string
  amount: LoanVaultTokenAmount
}

export interface ActivePrice {
  id: string
  key: string
  sort: string

  active?: {
    amount: string
    weightage: number
    oracles: {
      active: number
      total: number
    }
  }
  next?: {
    amount: string
    weightage: number
    oracles: {
      active: number
      total: number
    }
  }
  isLive: boolean

  block: {
    hash: string
    height: number
    time: number
    medianTime: number
  }
}

Transaction

List all transaction activity belonging to an address, sorted by block recency. See pagination

Code Samples

Shell

curl https://ocean.defichain.com/v0/mainnet/address/8defichainBurnAddressXXXXXXXdRQkSm/transactions

JavaScript (@defichain/whale-api-client)

await api.address.listTransaction('8defichainBurnAddressXXXXXXXdRQkSm', 30)

Response

{
  "data": [
    {
      "id": "0014dd65017e92b28c1f980be11591d6274b400d29a49ba0d1dac3d3e58472e2907edf5a9300000000",
      "hid": "e70680db7f28c22b9ef50a72b923e8991488a50f8b104022d92c42ebad7ee175",
      "type": "vout",
      "typeHex": "01",
      "txid": "7e92b28c1f980be11591d6274b400d29a49ba0d1dac3d3e58472e2907edf5a93",
      "block": {
        "hash": "2569c94596faff8337a0f0c9acec58fa745031d904aa435d918a9a8fc71ec3c7",
        "height": 1367397,
        "time": 1636979762,
        "medianTime": 1636979644
      },
      "script": {
        "type": "pubkeyhash",
        "hex": "76a914f7874e8821097615ec345f74c7e5bcf61b12e2ee88ac"
      },
      "vout": {
        "txid": "7e92b28c1f980be11591d6274b400d29a49ba0d1dac3d3e58472e2907edf5a93",
        "n": 0
      },
      "value": "50.00000000",
      "tokenId": 0
    }
  ],
  "page": {
    "next": "0014d607019867a4e1b65f3ecb7bcc6ad19464fdf0b7757369debfd1236a5a923a5effb39200000001"
  }
}

TypeScript Definitions

export interface AddressActivity {
  id: string
  hid: string

  type: 'vin' | 'vout'
  typeHex: '00' | '01'
  txid: string

  block: {
    hash: string
    height: number
    time: number
    medianTime: number
  }

  script: {
    type: string
    hex: string
  }

  vin?: {
    txid: string
    n: number
  }

  vout?: {
    txid: string
    n: number
  }

  value: string
  tokenId?: number
}