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:
- a filter, which lets you specify what subset of events you want
- 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.