Skip to main content


BETA API v0 & beyond

Ocean REST API is currently in public BETA, all endpoint is prefixed with /v0. As part of BirthdayResearch/jellyfishsdk#580 consolidation effort to creating better development synergy, /v1 of the API is undergoing redesign and will look very different from /v0. /v0 of the API is used in production by DeFiCh/wallet and DeFiCh/scan, the API will be long-lived with frequent incremental change with backward compatibility.

What is Ocean REST API?

Ocean REST API is a global infrastructure project hosted by DeFiChain to simplify building decentralized light applications. Powered by the Jellyfish Ecosystem, it features a super index that extends the capability of defid. The project is currently housed in JellyfishSDK/whale, they are getting consolidated into BirthdayResearch/jellyfishsdk as a single monorepo project.

Ocean Nodes are globally distributed around the world, any API request is served by the node nearest to the requester with auto fail-over.

How to use Ocean REST API?{version}/{network}

All API access is over HTTPS, and accessed from All data is sent and received as JSON. Multiple versions of the API are deployed at any time (e.g. /v0.14), we highly encourage you use /v0 of Ocean REST API at all times. Minor versioned endpoint are only used for testing new deployments, they are removed when merged into /v0.


HTTP/1.1 200 OK
Date: Fri, 19 Nov 2021 00:00:00 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 804
Connection: keep-alive
vary: Origin
access-control-allow-origin: *

"data": {

JS/TS Library

A full mapped JavaScript library @defichain/whale-api-client with rich TypeScript definitions is provided for each release.

npm i @defichain/whale-api-client
import { WhaleApiClient } from '@defichain/whale-api-client'

const client = new WhaleApiClient({
url: '',
timeout: 60000,
version: 'v0',
network: 'mainnet'

client.stats.get().then((data) => {



Most API with LIST operation can be paginated. All paginate-able resource endpoint in Ocean REST API represent one sort indexes/projection. Pagination within Ocean REST API is done via "slice window", if there are more items in your query, you are given a "next token" to get the next slice.

Making the first request


"data": [...],
"page": {
"next": "138"

Using next token to get next request


"data": [...]

When "page" is empty or undefined, it indicates there is no more item to query.

Pagination via JavaScript (@defichain/whale-api-client)

const firstPage = await api.address.listTransaction('address', 30)

// Automatically via api.paginate()
const nextPage = await api.paginate(firstPage)

// Manually via next token
const nextPage = await api.address.listTransaction('address', 30, firstPage.nextToken)