NAV Navbar
shell javascript

Introduction

ChainRelay provides RESTful smart contract APIs for you to build blockchain applications that don't require you to be an expert or spend time building infrastructure. This API is currently at version 0 (alpha) and may be subject to changes. Any changes will be communicated in advance via the email you provide when registering a token. Currently ChainRelay only supports the Ethereum mainnet (networkId = 1).

We currently offer two API resources: event history and event webhooks.

The contract event history API provides you with the ability to query past event logs for any contract on Ethereum. Make sure to register the contract ABI or choose a contract with a preloaded ABI.

The contract event webhooks API allows you to register for notifications when an event is emitted by an Ethereum smart contract. Once you create a webhook for a contract, the provided URL will receive a POST request every time a watched event is included into a new Ethereum block.

Authentication

Get API Token

Example request

curl --request GET \
  --url 'https://api.chainrelay.com/v0/create-token?email=you@example.com'
var request = require("request");

var options = {
  method: "GET",
  url: "https://api.chainrelay.com/v0/create-token",
  qs: { email: "you@example.com" }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example response

{
  "token":"API_TOKEN",
  "email": "you@example.com"
}

All queries to the ChainRelay API require an access token. Generate your unique access token with this endpoint.

HTTPS Request

GET https://api.chainrelay.com/v0/create-token

Query Parameters

Parameter Required Description
email true Create a new API token or retrieve an existing token associated with the passed email.

Contract ABIs

Save Contract ABI

Example request

curl -X POST \
  'https://api.chainrelay.com/v0/1/abis?token=API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "address": "0xe41d2489571d322189246dafa5ebde1f4699f498",
  "abi": []
}'
var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.chainrelay.com/v0/1/abis',
  qs: { token: 'API_TOKEN' },
  headers: { 'Content-Type': 'application/json' },
  body: {
    address: '0xe41d2489571d322189246dafa5ebde1f4699f498',
    abi: []
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Register a contract's ABI to retrieve its events. See below for a list of contracts that ChainRelay has pre-registered ABIs for.

HTTPS Request

POST https://api.chainrelay.com/v0/<networkId>/abis

Path Parameters

Parameter Required Description
networkId true Network ID of the desired Ethereum network.

Query Parameters

Parameter Required Description
token true Must use a valid API token.

Request Body JSON

Key Required Description
address true Address of the contract being registered.
abi true ABI of the contract being registered.

The ChainRelay API is preloaded with several contracts.

PreLoaded ERC 20 Token Contracts:

Contract Name Contract Address
0x (ZRX) 0xe41d2489571d322189246dafa5ebde1f4699f498
Tether (USDT) 0xdac17f958d2ee523a2206206994597c13d831ec7
Binance (BNB) 0xb8c77482e45f1f44de1745f52c74426c631bdd52
OmiseGo (OMG) 0xd26114cd6ee289accf82350c8d8487fedb8a0c07
Basic Attention Token (BAT) 0x0d8775f648430679a709e98d2b0cb6250d2887ef

PreLoaded ERC 721 Token Contracts:

Contract Name Contract Address
MLB Crypto Baseball 0x8c9b261faef3b3c2e64ab5e58e04615f8c788099
CryptoKitties 0x06012c8cf97bead5deae237070f9587f8e7a266d
Ethermon Adventure 0xbfde6246df72d3ca86419628cac46a9d2b60393c
Gods Unchained 0x6ebeaf8e8e946f0716e6533a6f2cefc83f60e8ab
War Riders 0x5caebd3b32e210e85ce3e9d51638b9c445481567

Contract Event History

Get Event History

Example request

curl -X GET \
  'https://api.chainrelay.com/v0/1/events/0xe41d2489571d322189246dafa5ebde1f4699f498'\
  '?token=API_TOKEN' \
  '&fromBlock=6302000' \
  '&toBlock=6307000'
var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api-dev.chainrelay.com/v0/1/events/0xe41d2489571d322189246dafa5ebde1f4699f498',
  qs: { token: 'API_TOKEN', fromBlock: 6302000 }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example response

{
  "query": {
    "fromBlock": 6302000,
    "toBlock": 6307000
  },
  "events": [
    ...,
    {
      "address":"0xE41d2489571d322189246DaFA5ebDe1F4699F498",
      "blockNumber":6281385,
      "transactionHash":"0x6d8a12b045a2ca5333c5e07c928aa8840650110ac86fafe1218a59d3c12f6c7b",
      "transactionIndex":122,
      "blockHash":"0x419ce6ef07e2007524bbf17873bb9ff8d446b27bc8bb6854ed367304ed692b0f",
      "logIndex":66,
      "removed":false,
      "id":"log_bd346201",
      "returnValues": {
        "0":"0xd3e2Ab7fEC89bbc7896105EeD2e898C4D04ec189",
        "1":"0x9f6FF0669E879e4AB2028cbA8127AAa2Dac17355",
        "2":"132337173635565969148",
        "_from":"0xd3e2Ab7fEC89bbc7896105EeD2e898C4D04ec189",
        "_to":"0x9f6FF0669E879e4AB2028cbA8127AAa2Dac17355",
        "_value":"132337173635565969148"
      },
      "event":"Transfer",
      "signature":"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
      "raw": {
        "data":"0x0000000000000000000000000000000000000000000000072c8c1644e7195efc",
        "topics": [
          "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
          "0x000000000000000000000000d3e2ab7fec89bbc7896105eed2e898c4d04ec189",
          "0x0000000000000000000000009f6ff0669e879e4ab2028cba8127aaa2dac17355"
        ]
      }
    }
  ]
}

Retrieve events from a registered contract. Rate limited to return just the next 1000 blocks by default. The maxiumum block range you can query for is 5000 blocks.

HTTPS Request

GET https://api.chainrelay.com/v0/<networkId>/events/<contractAddress>

Path Parameters

Parameter Required Description
networkId true Network ID of the desired Ethereum network.
contractAddress true Contract address in hexidecimal with preceding 0x.

Query Parameters

Parameter Required Description
token true Must use a valid API token.
fromBlock true Integer block number, at which to start retrieving events.
toBlock false Integer block number, at which to stop retrieving events. If omitted, the default is to return the next 1000 blocks.

Contract Event Webhooks

Webhooks provide you with a tool to notify another app or service when a contract event is emitted on Ethereum. In order to use our webhooks service, first you create a webhook by providing information about the events you would like to montior, and the URLs to request when new events are included in an Ethereum block. When ChainRelay detects a new Ethereum block containing an event that you have setup webhooks for, you will get a POST request containing all the events you have specified to watch.

ChainRelay provides you with an API to create webhooks, list all the webhooks you have created, and delete old hooks that are no longer useful.

Create Webhook

Example request

curl --request POST \
  --url 'https://api.chainrelay.com/v0/1/hooks?token=API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{\n "url": "https://example.com/webhook",\n "contract": {\n   "address": "0xe41d2489571d322189246dafa5ebde1f4699f498",\n    "name": "ZRX Token"\n  },\n  "events": ["*"],\n  "abi": []\n}'
var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.chainrelay.com/v0/1/hooks',
  qs: { token: 'API_TOKEN' },
  headers: { 'Content-Type': 'application/json' },
  body: { 
    url: 'https://example.com/webhook',
    contract: {
      address: '0xe41d2489571d322189246dafa5ebde1f4699f498',
      name: 'ZRX Token'
    },
    events: [ '*' ],
    abi: []
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example response

{
  "id": "25",
  "contract": {
    "address": "0xe41d2489571d322189246dafa5ebde1f4699f498",
    "name": "ZRX Token"
  },
  "abi": [],
  "headers": {},
  "events": [
    "*"
  ]
}

Create a webhook for contract events.

HTTPS Request

POST https://api.chainrelay.com/v0/<networkId>/hooks

Path Parameters

Parameter Required Description
networkId true Network ID of the desired Ethereum network.

Query Parameters

Parameter Required Description
token true Must use a valid API token.

Request Body JSON

Key Required Description
url true The url for the webhook to request.
headers false Any additional request headers you want in your webhook.
contract.address true The address of the contract for the webhook.
contract.name false A nickname for the contract.
abi true ABI of the contract being registered.
events false An array of contract event names, or "*" to receive all events. If events is not provided, the default is "*" for all events.

List Webhooks

Example request

curl --request GET \
  --url 'https://api.chainrelay.com/v0/1/hooks?token=API_TOKEN' \
  --header 'Content-Type: application/json'
var request = require("request");

var options = {
  method: 'GET',
  url: 'https://api.chainrelay.com/v0/1/hooks',
  qs: { token: 'API_TOKEN' },
  headers: { 'Content-Type': 'application/json' }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example response

{
  "count": 1,
  "hooks": [
    {
      "id": "25",
      "contract": {
        "address": "0xe41d2489571d322189246dafa5ebde1f4699f498",
        "name": "ZRX Token"
      },
      "abi": [],
      "headers": {},
      "events": [
        "*"
      ]
    }
  ]
}

List all webhooks created with the provided API token.

HTTPS Request

GET https://api.chainrelay.com/v0/<networkId>/hooks

Path Parameters

Parameter Required Description
networkId true Network ID of the desired Ethereum network.

Query Parameters

Parameter Required Description
token true Must use a valid API token.

Delete Webhook

Example request

curl --request DELETE \
  --url 'https://api.street.chainrelay.com/v0/1/hooks/25?token=API_TOKEN'
var request = require("request");

var options = {
  method: 'DELETE',
  url: 'https://api.chainrelay.com/v0/1/hooks/25',
  qs: { token: 'API_TOKEN' }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example response

{
  "removed": {
    "id": "25",
    "contract": {
      "address": "0xe41d2489571d322189246dafa5ebde1f4699f498",
      "name": "ZRX Token"
    },
    "abi": [],
    "headers": {},
    "events": [
      "*"
    ]
  }
}

Delete the webhook identified by the provided hook ID.

HTTPS Request

DELETE https://api.chainrelay.com/v0/<networkId>/hooks/<hookId>

Path Parameters

Parameter Required Description
networkId true Network ID of the desired Ethereum network.
hookId true The webhook ID.

Query Parameters

Parameter Required Description
token true Must use a valid API token.