Overview

Introduction

The n.xyz push API allows you to subscribe to updates to blockchain events that you care about. In real-time, as events you care about happen, the push API will send an HTTP POST request with event details to a webhook URL of your choice.

The API has two concepts:

1. a filter, which lets you specify what subset of events you want
2. a webhook, which specifies where you want to receive the notification.

Filter

To create a filter, use the CreateNewFilter endpoint. This lets you specify a set of wallet addresses, contract addresses and tokens. They must be specified as hex-formatted addresses. Note that:

• Within each field, the entries are implicitly ORed (that is, if you specify two wallet addresses, the filter will match both those addresses)
• Across fields, the entries are implicit ANDed (so if you specify a wallet address and a contract address, the filter will only match events by that wallet on that contract)
• If a field is blank, that implies “no filter” or “match all”. The corollary to this is that a filter with all empty fields will match all events.

When you successfully create a filter, the response from CreateNewFilter will include an id, which you can use to manage the filter. You can also use the ListFilters endpoint to list all filters at any time.

To update filters, you can use the UpdateFilter endpoint to replace the filter with your newly provided filter, or the PatchFilter endpoint to make incremental changes. You can use the DeleteFilter endpoint to delete filters.

Webhook

A filter by itself does not yet send notifications. For that, you must create webhooks. You can do this with the CreateNewWebhook endpoint. It must specify a URL (with protocol) that POST notifications will be sent to, a filter ID (from the filter you created above), a chain ID (for which blockchain you care about) and an event Type (currently, either “NFT” or “ERC20”). Once you create the webhook, you should start receiving notifications immediately, for all on-chain events starting at the time you created the webhook.

Similar to filters, you can list and delete webhooks using the API. Note that you can have multiple webhooks referencing the same filter; you can only delete a filter after deleting all webhooks that depend on it.

Format of Received Webhooks

The body of the HTTP POST requests sent to webhooks will contain a JSON object, with the schema of WebhookEvent. All relevant schemas are below.

WebhookEvent: {
    webhookID     string
    filterID     string
    filterVersion int 
    event Event
}


Event: {
    eventType string // Currently “NFT” or “ERC” 20
    chainID string
    event       EventData
    transaction TransactionData
}

EventData: {
    tokenStandard   string
    contractAddress string
    tokenID         string
    eventFrom       string
    eventTo         string
    eventValue      string
    logIndex        int64
}

TransactionData: {
    // Block level data.
    blockNumber string
    blockHash   string
    parentHash  string
    timestamp   int64
    // Transaction level data.
    transactionHash  string
    transactionIndex int64
    from             string
    to               string
  value                      string
}

Here is an example event:

{
  "webhookID": "ad382662-b0af-49eb-8bc6-ea5241ea84e7",
  "filterID": "2e23e55b-130b-420c-8453-09093ec43c03",
  "filterVersion": 1,
  "event": {
    "eventType": "NFT",
    "chainID": "ethereum",
    "event": {
      "tokenStandard": "ERC-721",
      "contractAddress": "0xa12faac5c839a5b6e98d0aa1e9d7503417cdf701",
      "tokenID": "1321",
      "eventFrom": "0x0000000000000000000000000000000000000000",
      "eventTo": "0x5ed269ceba88a65fd14c7e4b1521b4028f9d522c",
      "logIndex": 34
    },
    "transaction": {
      "blockNumber": "16092240",
      "blockHash": "0xefe6bedb6b9ec2c5daacdbb1a1784feb99b28ecad5feee605cfe106930353a9b",
      "parentHash": "0xd8186b716949bbe51c4fee1c39a7fdfe15aca89342c2f4f568af92dbbf233925",
      "timestamp": 1669925291,
      "transactionHash": "0xd763ac5699c8787cfd35b3ef41991454d39cae8c42d5dae7b04da6e8c8a06f90",
      "transactionIndex": 40,
      "from": "0x5ed269ceba88a65fd14c7e4b1521b4028f9d522c",
      "to": "0xa12faac5c839a5b6e98d0aa1e9d7503417cdf701",
      "value": "1000000000000000"  
    }
  }
}

Note on organizations and API keys

Note that all filters and webhooks are currently scoped to an organization. This means that any API key belonging to an organization can create/update/delete a filter/webhook in the organization, as well as view all filters/webhooks in the organization, including those created by other API keys in the organization.

Note on error handling

If there is an error sending an event to the webhook, NXYZ will retry for up to 24 hours. Retries are made in the 24 hour period with an exponential backoff, with a maximum interval of 2 minutes between retries. If the webhook recovers within 24 hours, all updates will be sent, without drops. If the webhook recovers only after 24 hours, NXYZ will only send on-chain updates on or after the time it detects that the webhook has recovered.

Note on reorgs

Webhooks run at finality 0, which means that events are streamed as soon as they are observed. If a reorg occurs, nxyz will stream events from sequential blocks starting from the reorg fork point. Currently, there is no indicator message streamed in the event of a reorg; rather, it's possible to detect a reorg by observing new block numbers less than those already streamed.