Skip to main content

Using Oracle API

Hi everyone, welcome to the Cordial Oracle API guide. In this guide you will subscribe to an external addresses on Ethereum blockchain to query its balances and transactions.

Overview

Oracle tracks a list of addresses someone is subscribed to and fetches balances and transactions for these addresses in a scheduled manner. The fetched data can then be queried via API with pagination support. If the address is no longer needed you can unsubscribe from it, although the data that was fetched so far will not be deleted from the storage.

Prerequisites

To start this guide do these two things:

  1. Create and set API Key accordingly
  2. Set BASE_URL in shell to use either testnet or mainnet (We will use testnet in this guide):
    For testnet: BASE_URL=https://oracle-testnet.cordialapis.com
    For mainnet: BASE_URL=https://oracle.cordialapis.com

Subscribing to an address

To subscribe to some address you need to send a simple no-body PUT request containing only the address and chain to which this address belongs. Let's subscribe to some address on Ethereum Sepolia:

curl --request PUT \
  --url "$BASE_URL/v1/chains/ETH/addresses/0x13cb6ae34a13a0977f4d7101ebc24b87bb23f0d5" \
  -u $API_ID:$API_SECRET

So you start listening to all the transactions and balances for address 0x13cb6ae34a13a0977f4d7101ebc24b87bb23f0d5 on the test ETH network.

Let's verify the subscription exists now by listing all the addresses you are subscribed to:

curl --request GET \
  --url "$BASE_URL/v1/addresses" \
  -u $API_ID:$API_SECRET

The response is:

{
  "addresses":
    ["chains/ETH/addresses/0x13cb6ae34a13a0977f4d7101ebc24b87bb23f0d5"],
  "next_page_token": "",
  "total_size": 1,
}

As we can see, the address we just subscribed to is listed in the response, which means we can now query its balances and transactions.

Hint: If you want to see addresses for some specific chain only you can achieve that via a similar request:

curl --request GET \
  --url "$BASE_URL/v1/chains/ETH/addresses" \
  -u $API_ID:$API_SECRET

Querying address data

Once the address is subscribed Oracle starts recording its data with some interval.

Balances​

Let's wait around 3 minutes and query the address balances.

curl --request GET \
  --url "$BASE_URL/v1/chains/ETH/addresses/0x13cb6ae34a13a0977f4d7101ebc24b87bb23f0d5/balances" \
  -u $API_ID:$API_SECRET

In response we get all the address balances.

Transactions​

We can also see address transactions now, but addresses typically have a lot of transactions and we don't want all of them at once. Let's see how pagination can help us with that.

curl --request GET \
  --url "$BASE_URL/v1/chains/ETH/addresses/0x13cb6ae34a13a0977f4d7101ebc24b87bb23f0d5/transactions?page_size=1" \
  -u $API_ID:$API_SECRET

Note: We specified the page_size query parameter which limits the response to contain only one transaction at a time.

In response, we get a page of transactions.

As you can see, the response contains only one transaction, and it is the most recent one.
How can we iterate further down to the older transactions?
By using page_token query parameter! Note that the first response contains the next_page_token field. We can now pass this token as the query parameter to go further.

curl --request GET \
  --url "$BASE_URL/v1/chains/ETH/addresses/0x13cb6ae34a13a0977f4d7101ebc24b87bb23f0d5/transactions?page_token=eyJzIjoxLCJvIjoxNDk3MX0" \
  -u $API_ID:$API_SECRET

This way, we can consecutively reuse the returned next_page_token to go deeper down the chain.

Hint: You can also change the page_size during the iteration without regeneration of the page token.

Get individual transactions​

Let's take transaction on ETH with hash 0xa52c92804ec2bd2436cc048d663e2d916e0433f009e75df8b1084356177de713.

curl --request GET \
  --url "$BASE_URL/v1/chains/ETH/transactions/0xa52c92804ec2bd2436cc048d663e2d916e0433f009e75df8b1084356177de713" \
  -u $API_ID:$API_SECRET

As you can see, the response contains all the available information about the transaction, including the amount, fees, sender and recipient.

Unsubscribing addresses

If you no longer need to listen to some address you can easily unsubscribe from it:

curl --request DELETE \
  --url "$BASE_URL/v1/chains/ETH/addresses/0x13cb6ae34a13a0977f4d7101ebc24b87bb23f0d5" \
  -u $API_ID:$API_SECRET

The data that was previously collected will not be deleted from the storage, but you will not be able to access it now:

curl --request GET \
  --url "$BASE_URL/v1/chains/ETH/addresses/0x13cb6ae34a13a0977f4d7101ebc24b87bb23f0d5/balances" \
  -u $API_ID:$API_SECRET

The response is expected:

{
  "code": 16,
  "message": "Requester is not subscribed for address '0x13cb6ae34a13a0977f4d7101ebc24b87bb23f0d5'",
  "status": "Unauthenticated",
}

Congratulations! You just completed the guide where you went through the most essential Oracle API endpoints.