curl --request POST \
--url https://api.zerion.io/v1/tx-subscriptions/ \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"callback_url": "https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3",
"addresses": [
"0x42b9df65b219b3dd36ff330a4dd8f327a6ada990"
]
}
'import requests
url = "https://api.zerion.io/v1/tx-subscriptions/"
payload = {
"callback_url": "https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3",
"addresses": ["0x42b9df65b219b3dd36ff330a4dd8f327a6ada990"]
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
callback_url: 'https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3',
addresses: ['0x42b9df65b219b3dd36ff330a4dd8f327a6ada990']
})
};
fetch('https://api.zerion.io/v1/tx-subscriptions/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.zerion.io/v1/tx-subscriptions/"
payload := strings.NewReader("{\n \"callback_url\": \"https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3\",\n \"addresses\": [\n \"0x42b9df65b219b3dd36ff330a4dd8f327a6ada990\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"data": {
"type": "transactions_subscription",
"id": "52d994a173d755e99845e861d534a419",
"attributes": {
"callback_url": "https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3",
"created_at": "2022-08-15T11:26:31+00:00",
"updated_at": "2022-08-15T11:26:31+00:00",
"expires_at": "9999-12-31T23:59:59Z",
"enabled": true,
"filters": {
"exclude": {
"types": [
"send"
],
"is_spam": true,
"protocol_ids": [
"uniswap-v3"
],
"addresses": [
"0x0000000000000000000000000000000000000001"
]
}
}
},
"relationships": {
"chains": [
{
"links": {
"related": "https://api.zerion.io/v1/chains/polygon"
},
"data": {
"type": "chains",
"id": "polygon"
}
}
]
}
}
}{
"errors": [
{
"title": "Parameter is malformed",
"detail": "Some validation errors will be described here"
}
]
}{
"errors": [
{
"title": "Unauthorized Error",
"detail": "The API key is invalid, please, make sure that you are using a valid key"
}
]
}{
"errors": [
{
"title": "Forbidden",
"detail": "unpaid keys can only move expires_at earlier"
}
]
}{
"errors": [
{
"title": "Too many requests",
"detail": "Your request had been throttled"
}
]
}Create subscription
Create a webhook subscription that pushes transaction notifications for a set of wallets to your callback URL.
curl --request POST \
--url https://api.zerion.io/v1/tx-subscriptions/ \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"callback_url": "https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3",
"addresses": [
"0x42b9df65b219b3dd36ff330a4dd8f327a6ada990"
]
}
'import requests
url = "https://api.zerion.io/v1/tx-subscriptions/"
payload = {
"callback_url": "https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3",
"addresses": ["0x42b9df65b219b3dd36ff330a4dd8f327a6ada990"]
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
callback_url: 'https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3',
addresses: ['0x42b9df65b219b3dd36ff330a4dd8f327a6ada990']
})
};
fetch('https://api.zerion.io/v1/tx-subscriptions/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.zerion.io/v1/tx-subscriptions/"
payload := strings.NewReader("{\n \"callback_url\": \"https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3\",\n \"addresses\": [\n \"0x42b9df65b219b3dd36ff330a4dd8f327a6ada990\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"data": {
"type": "transactions_subscription",
"id": "52d994a173d755e99845e861d534a419",
"attributes": {
"callback_url": "https://webhook.site/fcd606d2-f5bd-4832-9874-ff07c980b5a3",
"created_at": "2022-08-15T11:26:31+00:00",
"updated_at": "2022-08-15T11:26:31+00:00",
"expires_at": "9999-12-31T23:59:59Z",
"enabled": true,
"filters": {
"exclude": {
"types": [
"send"
],
"is_spam": true,
"protocol_ids": [
"uniswap-v3"
],
"addresses": [
"0x0000000000000000000000000000000000000001"
]
}
}
},
"relationships": {
"chains": [
{
"links": {
"related": "https://api.zerion.io/v1/chains/polygon"
},
"data": {
"type": "chains",
"id": "polygon"
}
}
]
}
}
}{
"errors": [
{
"title": "Parameter is malformed",
"detail": "Some validation errors will be described here"
}
]
}{
"errors": [
{
"title": "Unauthorized Error",
"detail": "The API key is invalid, please, make sure that you are using a valid key"
}
]
}{
"errors": [
{
"title": "Forbidden",
"detail": "unpaid keys can only move expires_at earlier"
}
]
}{
"errors": [
{
"title": "Too many requests",
"detail": "Your request had been throttled"
}
]
}Authorizations
To test endpoints here, paste your API key from the Dashboard into the username field and leave the password empty.
Body
Chains to report transactions from. Only chains reporting both supports_transactions and supports_positions in the flags of GET /v1/chains/ are accepted here.
Naming a chain that fails that gate returns 400 rather than an empty result, with detail reading chain <id> does not support transactions. That detail names the endpoint's capability rather than the flag that failed, so bob is refused with chain bob does not support transactions even though it reports supports_transactions. What it lacks is supports_positions.
Leave the list empty to subscribe to every chain that passes the gate. Chains that fail it are left out silently, with no error and no meta signal.
Exclusion filters for the subscription. Conditions are combined with OR: an
event matching any one of them is dropped and no webhook is delivered for it.
Filters are absent from the response when none are set. What omitting the
field or sending null means is specific to the request that carries it:
see that operation's own description.
Field paths below refer to the delivered webhook transaction payload, not to
this subscription resource. A condition does not match an event lacking the
value it compares, so an event with no dapp is not excluded by
protocol_ids.
Show child attributes
Show child attributes
Time the subscription expires, as an RFC 3339 timestamp with an offset (Z or +03:00), for example 2026-12-31T00:00:00Z. It's stored in UTC, truncated to milliseconds. At this time the subscription is deleted along with its wallets. Defaults to never, which reads back as 9999-12-31T23:59:59Z. Sending null also means never.
The value must be at least 1 minute in the future. There is no maximum. A malformed value, or one earlier than 1 minute from now, returns 400.
On the free plan (keys of organizations without a paid plan, and dev keys that don't belong to an organization), a subscription defaults to expiring 7 days after creation, and expires_at can be at most 7 days from now. A later value, or null, returns 403.
"2026-12-31T00:00:00Z"
Callbacks
Was this page helpful?