Skip to main content

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
}