Webhooks (Lambda) via dRPC
Webhooks tell your server when something happens on chain to the addresses you care about. You
register a callback URL and a list of addresses. When one of them sends or receives anything, we
send a signed POST to your URL a few seconds after the block. The transaction in it is decoded
the same way the Transactions API returns it: transfers with token metadata and USD values, the
fee, and Lambda's operation label (swap tokens, deposit into liquidity pool, receive, ...).
For Ethereum stakers there is an opt-in staking feed on top of that: validator rewards, payouts split into reward and returned stake, deposits and status changes. See Staking webhooks.
Overview#
Supported chains
ethereum, base, polygon, bsc, arbitrum, optimism, avalanche, monad.
A subscription with an empty chain_ids covers all of them, and any chain we add later.
Access
Webhooks belong to the DRPC Data & Wallet API and use the same key and base URL:
- Log in to the dRPC dashboard, open API Keys and select your key.
- Copy the base URL from the Data & Wallet API card. It looks like
https://lb.drpc.live/lambda/<YOUR_API_TOKEN>. - Webhook endpoints are under
/v1/webhooks/subscriptionson that base URL:
https://lb.drpc.live/lambda/<YOUR_API_TOKEN>/v1/webhooks/subscriptionsThere is no per-chain URL. A subscription picks its chains in chain_ids.
Pricing
| Action | CU |
|---|---|
| Any management call (create, list, get, update, enable, disable, delete, add/remove addresses, list addresses) | 20 CU per call |
One delivered webhook (one POST to your callback URL) | 20 CU |
A delivery is charged once, when it is delivered, no matter how many attempts it took.
Retractions after a reorg and subscription notices are free. A transaction that moved only spam
tokens is neither delivered nor charged, unless you opted in with include_spam.
Deliveries are paid from the same balance and daily limit as your other requests. When either runs out, deliveries stop and you get a subscription notice (see Subscription notices). Events from that period are not queued.
Limits
| Limit | Value |
|---|---|
| Subscriptions per account | 50 |
| Addresses per subscription | 10,000 |
| Addresses per account, all subscriptions together | 100,000 (can be raised on request) |
| Addresses per call (create, add/remove) | 100 |
| Time your server has to answer a delivery | 10 s |
Addresses you cannot subscribe to
Create and add/remove calls reject some addresses with 422. The response names each refused
address and why:
- Token contracts, such as an ERC-20 contract. A subscription on one would receive every transfer of the token.
- Blocklisted addresses. Wallets that stayed above certain number of transactions (exchange hot wallets, bots),
DEX routers, chain system contracts, burn addresses (zero,
0x…dead,0x11…11), and a few shared staking contracts. We deliver a subscription's webhooks one at a time, so an address that busy would outrun any endpoint. Once an address is on the blocklist it stays there.
Quickstart#
1. Create a subscription
curl --request POST \
--url 'https://lb.drpc.live/lambda/<YOUR_API_TOKEN>/v1/webhooks/subscriptions' \
--header 'Content-Type: application/json' \
--data '{
"callback_url": "https://example.com/hooks/lambda",
"addresses": ["0x04fC43d86DEee3185B77f0D520D8932462814e02"],
"chain_ids": ["ethereum", "base"]
}'{
"id": "0450d9f4-304f-420f-9b49-3625d9c52c1f",
"callback_url": "https://example.com/hooks/lambda",
"status": "enabled",
"chain_ids": ["ethereum", "base"],
"filters": {},
"address_count": 1,
"created_at": "2026-09-21T12:52:46.024339Z",
"updated_at": "2026-09-21T12:52:46.024339Z"
}The subscription works right away: the first matching transaction after this moment is
delivered. Nothing from before it is. Addresses are stored in lowercase, and any 0x spelling
matches.
2. Receive a webhook
When one of your addresses is in a transaction, your URL gets:
POST /hooks/lambda HTTP/1.1
Content-Type: application/json
X-Lambda-Signature: t=1790001557, v1=<base64 signature>
X-Lambda-Key-Id: primary
X-Lambda-Sequence: 42The body is described in Delivery payload. Answer with any 2xx within 10
seconds.
3. Verify the signature
Every delivery is signed with Ed25519. The signed message is <t>.<raw body> as UTF-8: the t
value from the header, a dot, and the body exactly as you received it.
Public keys are published as a JWKS, no authentication needed:
https://api.lambda.p2p.org/.well-known/jwks.jsonTake the key whose kid equals X-Lambda-Key-Id. Cache the document, and fetch it again when
you see a kid you don't know: that is how a new key reaches you. Also reject deliveries whose
t is more than a few minutes away from your clock, so an old request can't be replayed.
Node.js:
import { createPublicKey, verify } from "node:crypto";
// jwk is the JWKS key whose kid matches the X-Lambda-Key-Id header
function verifyDelivery(jwk, signatureHeader, rawBody) {
const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.trim().split("=", 2)));
const key = createPublicKey({ key: { kty: "OKP", crv: "Ed25519", x: jwk.x }, format: "jwk" });
const message = Buffer.from(`${parts.t}.${rawBody}`, "utf8");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && verify(null, message, key, Buffer.from(parts.v1, "base64"));
}Python:
import base64, time
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
def verify_delivery(jwk: dict, signature_header: str, raw_body: bytes) -> bool:
parts = dict(p.strip().split("=", 1) for p in signature_header.split(","))
x = jwk["x"] + "=" * (-len(jwk["x"]) % 4)
key = Ed25519PublicKey.from_public_bytes(base64.urlsafe_b64decode(x))
if abs(time.time() - int(parts["t"])) > 300:
return False
try:
key.verify(base64.b64decode(parts["v1"]), parts["t"].encode() + b"." + raw_body)
return True
except Exception:
return FalseVerify against the raw body bytes. If you parse the JSON and serialize it again, the bytes change and the signature won't match.
4. Clean up
curl --request DELETE \
--url 'https://lb.drpc.live/lambda/<YOUR_API_TOKEN>/v1/webhooks/subscriptions/0450d9f4-304f-420f-9b49-3625d9c52c1f'The Subscription object#
{
"id": "0450d9f4-304f-420f-9b49-3625d9c52c1f",
"callback_url": "https://example.com/hooks/lambda",
"status": "enabled",
"chain_ids": [],
"filters": {},
"address_count": 1,
"created_at": "2026-09-21T12:52:46.024339Z",
"updated_at": "2026-09-21T12:52:46.024339Z"
}| Field | Meaning |
|---|---|
status | enabled or disabled. Only enabled subscriptions get deliveries |
chain_ids | lowercase chain slugs. [] means every supported chain, including future ones |
filters | see below |
address_count | how many addresses the subscription watches. The list itself is never inlined; page through it with List Addresses |
filters can hold two keys:
include_spam: true. By default, a transaction in which your address moved only spam tokens (airdrop dust, scam tokens, address-poisoning lookalikes) is not delivered and not charged. With this flag it is delivered, withflags.is_spam: true.event_kinds: ["staking"]turns on the Ethereum staking feed. It can only be set when the subscription is created. See Staking webhooks.
Any other key, an unknown event kind or a value of the wrong type is rejected with 422.
All management calls see only your own subscriptions. Another account's subscription id gets
404, the same as an id that doesn't exist.
Errors use one format, {"message": "<detail>"}: 401 for a missing or invalid key, 404 for
an unknown subscription, 422 for validation and quota errors.
Endpoints#
All paths are relative to https://lb.drpc.live/lambda/<YOUR_API_TOKEN>.
Create Subscription [Value: 20 CU]
POST /v1/webhooks/subscriptions → 201 with the Subscription object.
{
"callback_url": "https://example.com/hooks/lambda",
"addresses": ["0x04fC43d86DEee3185B77f0D520D8932462814e02"],
"chain_ids": ["ethereum", "base"],
"filters": {}
}| Body field | Required | Rules |
|---|---|---|
callback_url | yes | https:// only, on a public host. Private and reserved IPs, localhost and internal suffixes are rejected |
addresses | yes | 1 to 100 per call; add the rest with Add / Remove Addresses. Hex addresses are lowercased |
chain_ids | no | up to 50 slugs. Omit it or send [] for all chains |
filters | no | {}, {"include_spam": true}, {"event_kinds": ["staking"]}, or both keys |
Going over a quota (50 subscriptions, 10,000 addresses per subscription, 100,000 per account)
returns 422. There is also a service-wide capacity limit, which answers
422 address capacity reached; contact support.
List Subscriptions [Value: 20 CU]
GET /v1/webhooks/subscriptions → 200 with an array of Subscription objects in any status.
filter[chain_ids]=<slug> keeps only subscriptions that cover that chain. A subscription with
empty chain_ids covers every chain, so it always matches.
Get Subscription [Value: 20 CU]
GET /v1/webhooks/subscriptions/{id} → 200 with the Subscription object.
List Addresses [Value: 20 CU]
GET /v1/webhooks/subscriptions/{id}/addresses?limit=100&cursor= → 200:
{
"items": [
{ "address": "0x04fc43d86deee3185b77f0d520d8932462814e02", "activated_at": "2026-09-21T12:52:46.024339Z" }
],
"next_cursor": "MHgwNGZjNDNkODZkZWVlMzE4NWI3N2YwZDUyMGQ4OTMyNDYyODE0ZTAy"
}| Query param | Meaning |
|---|---|
limit | 1 to 1000, default 100 |
cursor | the previous page's next_cursor; leave it out for the first page. next_cursor is null on the last page |
Addresses come sorted, so paging while you add or remove addresses never repeats or skips one that was there the whole time.
activated_at is when the address started being watched. Transactions before that moment are
never delivered for it. If you remove an address and add it back, it keeps its first
activated_at.
Update Subscription [Value: 20 CU]
PATCH /v1/webhooks/subscriptions/{id} → 200 with the updated object.
{ "callback_url": "https://example.com/hooks/v2", "chain_ids": ["ethereum"] }Send any of callback_url, chain_ids, filters, at least one (422 otherwise). Fields you
leave out don't change. The same rules as on create apply, with two additions:
filtersreplaces the stored filters as a whole, so send every key you want to keep.event_kinds: ["staking"]cannot be added or removed here. On a staking subscription, keep it in everyfiltersyou send.
Add / Remove Addresses [Value: 20 CU]
PATCH /v1/webhooks/subscriptions/{id}/wallets → 200 with the updated object. Its
address_count reflects the change; the addresses are not echoed back.
{ "add": ["0xNewAddress"], "remove": ["0xOldAddress"] }Up to 100 addresses per call, add and remove together. Either list can be empty. The same
address in both lists is a 422. New addresses get activated_at = now; addresses you add back
keep their old one. The count after the change must stay within the per-subscription quota.
Enable Subscription [Value: 20 CU]
POST /v1/webhooks/subscriptions/{id}/enable → 200 with the updated object. Delivery resumes
from this moment. Transactions that happened while the subscription was disabled are not
delivered.
Disable Subscription [Value: 20 CU]
POST /v1/webhooks/subscriptions/{id}/disable → 200 with the updated object. Nothing is
matched or queued while it is disabled.
Delete Subscription [Value: 20 CU]
DELETE /v1/webhooks/subscriptions/{id} → 204, empty body. Deliveries stop within seconds.
This can't be undone. A delivery already on its way may still arrive.
Signing keys
GET https://api.lambda.p2p.org/.well-known/jwks.json → 200. No authentication, not charged.
A standard JWKS (RFC 7517):
{
"keys": [
{
"kty": "OKP",
"crv": "Ed25519",
"x": "uaGsSit6lCLIe9GtU2ebXN7kB1BBkXNrjtUMJ_wDNYY",
"kid": "primary",
"use": "sig",
"alg": "EdDSA"
}
]
}x is the raw 32-byte Ed25519 public key in base64url.
Deliveries#
Headers
| Header | Example | Meaning |
|---|---|---|
X-Lambda-Signature | t=1790001557, v1=<base64> | Ed25519 signature over <t>.<body> |
X-Lambda-Key-Id | primary | which JWKS key signed it |
X-Lambda-Sequence | 42 | a counter per subscription, growing with each new delivery |
Delivery payload
You get one delivery per watched address in the transaction. If two of your addresses are in the same transaction, you get two deliveries, each written from the point of view of its own address.
The body is a JSON:API document: an envelope in data and one transactions object in
included.
{
"data": {
"id": "7c0a6c4e-2d3b-4f6a-9c1e-5b8d2f0a1e33",
"type": "callback",
"attributes": {
"timestamp": "2026-09-21T16:05:12Z",
"callback_url": "https://example.com/hooks/lambda",
"address": "0x04fc43d86deee3185b77f0d520d8932462814e02"
},
"relationships": {
"subscription": { "type": "tx-subscriptions", "id": "0450d9f4-304f-420f-9b49-3625d9c52c1f" }
}
},
"included": [
{
"type": "transactions",
"id": "3f2b1c9d8e7a6b5c4d3e2f1a0b9c8d7e",
"attributes": {
"address": "0x04fc43d86deee3185b77f0d520d8932462814e02",
"operation_type": "receive",
"hash": "0xbed4122f4678ab33f94f1611740756b1afbb6d0c9f5fc26b6a8b036a0110218d",
"mined_at": "2026-09-21T16:05:11Z",
"mined_at_block": 23345187,
"sent_from": "0xa4a4bf6e23520bd0e05189f11fc3e81b51787e11",
"sent_to": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"status": "confirmed",
"nonce": null,
"fee": null,
"transfers": [
{
"fungible_info": {
"name": "Tether USD",
"symbol": "USDT",
"implementations": [{ "chain_id": "ethereum", "address": "0xdac17f958d2ee523a2206206994597c13d831ec7", "decimals": 6 }]
},
"direction": "in",
"quantity": { "int": "2500000000", "decimals": 6, "float": 2500.0, "numeric": "2500.000000" },
"price": 1.0,
"value": 2500.0,
"sender": "0xa4a4bf6e23520bd0e05189f11fc3e81b51787e11",
"recipient": "0x04fc43d86deee3185b77f0d520d8932462814e02"
}
],
"approvals": [],
"flags": { "is_spam": false },
"application_metadata": {
"name": "tether",
"contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
"method": { "id": "0xa9059cbb", "name": "transfer" }
}
},
"relationships": {
"chain": { "type": "chains", "id": "ethereum" },
"dapp": null
}
}
]
}| Field | Meaning |
|---|---|
data.id | the delivery id. Use it to drop duplicates |
data.attributes.address | the watched address this delivery is about (null on a subscription notice) |
data.relationships.subscription.id | the subscription |
included[0].id | transaction id, the same in every delivery of this transaction |
attributes.operation_type | Lambda's label when we recognise the transaction (swap tokens, deposit into liquidity pool, withdraw from staking, borrow from lending, ...); otherwise one of receive, send, trade, execute. New labels appear over time, so treat it as free text, not a fixed list |
attributes.transfers[] | every transfer in the transaction that touches your address. direction is in, out or self relative to it. Tokens and the gas token (address: null) come with fungible_info, NFTs with nft_info |
quantity | int is the raw amount as a string, plus decimals, a float, and numeric, the exact amount as a decimal string |
price, value | USD price and value at delivery time; null when we don't have a price |
attributes.fee | the gas paid, only when your address paid it; null otherwise |
attributes.flags.is_spam | true when the transaction moved a spam token. Spam-only transactions are skipped unless you set include_spam: true; a transaction with spam next to real transfers is always delivered, with the flag |
attributes.application_metadata | the contract and method called, when we know them |
attributes.events_omitted | true when the transaction was too large to ship with its transfers. Fetch it by hash from the Transactions API |
relationships.chain.id | chain slug, same values as chain_ids |
Movements that happen at block level without a transaction, such as validator withdrawals on
Ethereum, have hash = block_<number>. On a staking subscription withdrawals come from the
staking feed instead and look different; see Staking webhooks.
Retractions
If a reorg drops a transaction we already told you about, a second delivery arrives for it with
"deleted": true. Undo whatever you did with the first one.
{
"data": { "...": "the usual envelope, same address and subscription" },
"included": [
{
"type": "transactions",
"id": "3f2b1c9d8e7a6b5c4d3e2f1a0b9c8d7e",
"attributes": { "hash": "0xbed4122f…", "deleted": true }
}
]
}Subscription notices
When we can no longer charge the key behind a subscription (balance or daily limit used up, key
disabled), you get one notice. It has the usual envelope with address: null, and a
subscription-notices object instead of a transaction:
{
"data": { "...": "envelope with \"address\": null" },
"included": [
{
"type": "subscription-notices",
"id": "notice_suspended_1790001557",
"attributes": { "notice": "suspended", "reason": "balance_exceeded", "since": "2026-09-21T16:05:12Z" }
}
]
}While suspended, nothing is delivered and nothing is queued. When the key works again, a second notice follows:
{ "notice": "resumed", "since": "2026-09-21T16:05:12Z", "until": "2026-09-21T18:40:02Z" }Events between since and until were not delivered. If you need them, get them from the
Transactions API.
reason is one of balance_exceeded, day_limit_exceeded (resets at 00:00 UTC),
free_balance_exceeded, key_disabled, key_not_found. Notices skip the queue, so one can
arrive before deliveries that were already waiting.
Delivery rules
| Acknowledging | answer 2xx within 10 seconds |
| Retries | a timeout or a 5xx is retried. Three attempts in total: the second about 20 s after the first, the third about 40 s after the second. After that the delivery is dropped. Any 4xx means "don't retry" |
| Duplicates | possible, delivery is at least once. Drop repeats by data.id |
| Order | new deliveries of one subscription go out in X-Lambda-Sequence order. There is no order across chains, and notices can overtake waiting deliveries |
| Latency | a few seconds after the block. Staking feed deliveries are slower, see below |
| Charging | 20 CU per delivered webhook, once. Retractions and notices are free |
Staking webhooks#
This is for addresses that stake ETH: the address you deposit validators from, or the address validator withdrawals are paid to. Turn it on and, besides the usual deliveries, you also get what happens to your validators on the beacon chain:
- each payout to your address, marked as a reward sweep or an exit, with the exit split into returned stake and reward;
- consensus rewards and penalties every epoch;
- execution rewards (priority fees and MEV) for blocks your validators proposed;
- deposits being credited, status changes, exit and withdrawal requests, consolidations.
The typical use is reconciliation. A plain transfer says "0.0187 ETH arrived". With staking on, the same payout says "0.0187 ETH arrived, it is a reward sweep from validator 1048576". On an exit you see that 32 ETH of a 32.0166 ETH payout is your own stake coming back, so you don't book it as income.
Only Ethereum is covered.
Turning it on
Add event_kinds when you create the subscription:
curl --request POST \
--url 'https://lb.drpc.live/lambda/<YOUR_API_TOKEN>/v1/webhooks/subscriptions' \
--header 'Content-Type: application/json' \
--data '{
"callback_url": "https://example.com/hooks/staking",
"addresses": ["0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9012345"],
"chain_ids": ["ethereum"],
"filters": {"event_kinds": ["staking"]}
}'Rules:
chain_idsmust be empty or includeethereum. Otherwise422.- The setting is fixed for the life of the subscription. You can't add it to an existing
subscription or remove it later; both are
422. To stop getting staking data, create a new subscription without it and delete the old one. - Subscribe with the address you deposit from or the address your validators withdraw to. Validators are linked to it in either role.
- Staking data starts from the moment the subscription is created. Older rewards and payouts are not sent.
- A few shared contracts (the P2P.org deposit executor and some fee forwarders) can't be subscribed to. They are shared by many stakers, and a subscription on them would show other people's validators.
What arrives
Staking deliveries use the same envelope, headers, signature and retries as everything else.
One delivery covers one beacon slot and one of your addresses. In included it has one or both
of these:
- a
transactionsobject, if a validator payout landed on the address in that slot; - a
staking-eventsobject, for everything else that happened to your validators in that slot.
If nothing happened to your validators in a slot, nothing is sent for it.
A payout
{
"data": {
"id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
"type": "callback",
"attributes": {
"timestamp": "2026-11-04T00:41:07Z",
"callback_url": "https://example.com/hooks/staking",
"address": "0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9012345"
},
"relationships": {
"subscription": { "type": "tx-subscriptions", "id": "9b7e1d2a-4c3f-4e8a-b1d0-6f2a9c8e7d15" }
}
},
"included": [
{
"type": "transactions",
"id": "5e1f0c9a7b3d2e4f6a8c0b1d3e5f7a9c",
"attributes": {
"address": "0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9012345",
"operation_type": "receive staking withdrawal",
"hash": "slot_15577216",
"mined_at": "2026-11-04T00:03:35Z",
"mined_at_block": 26337666,
"sent_from": null,
"sent_to": null,
"status": "confirmed",
"nonce": null,
"fee": null,
"transfers": [
{
"fungible_info": {
"name": "Ethereum",
"symbol": "ETH",
"implementations": [{ "chain_id": "ethereum", "address": null, "decimals": 18 }]
},
"direction": "in",
"quantity": { "int": "18734512000000000", "decimals": 18, "float": 0.018734512, "numeric": "0.018734512000000000" },
"price": 3890.2,
"value": 72.88,
"sender": null,
"recipient": "0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9012345",
"staking": {
"kind": "partial",
"validator_index": 1048576,
"validator_pubkey": "0xa83c…9f1e",
"deposit_address": "0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9012345",
"share": "1",
"amount": "18734512000000000",
"principal_amount": "0",
"reward_amount": "18734512000000000",
"principal_loss": null,
"withdrawal_index": 98234117
}
}
],
"approvals": [],
"flags": { "is_spam": false }
},
"relationships": {
"chain": { "type": "chains", "id": "ethereum" },
"dapp": null
}
}
]
}How it differs from an ordinary transaction:
hashis not a transaction hash. A withdrawal has no transaction, so we use the slot:slot_<slot>, orslot_<slot>_catchup_<n>for a catch-up.mined_at_blockis the execution block of that slot.fee,sent_from,sent_toand each transfer'ssenderarenull.- There is one transfer per withdrawal. If several of your validators were paid in the same slot, they are all in one delivery.
quantityis what actually arrived on chain. It is the same as the withdrawal amount you would see in a block explorer.
The staking block on each transfer:
| Field | Meaning |
|---|---|
kind | partial: the validator's balance above its limit was swept out, normally rewards. full: the validator has exited and its whole balance was paid out |
validator_index, validator_pubkey | the validator that paid |
withdrawal_index | the beacon chain's withdrawal number. Unique, so it is a good key for deduplication |
deposit_address | the subscribed address this validator belongs to. null if the money landed on your address but the validator belongs to someone else (see below) |
share | your share of the validator as a fraction, for example "1" or "3/4". Currently always "1" |
amount | your part of the payout in wei: the payout × share |
reward_amount, principal_amount | the split of amount into reward and returned stake, in wei. null when the principal isn't known (see How the split works) |
principal_loss | on a full payout that came in under the principal, the shortfall in wei. null otherwise |
Everything else: staking-events
{
"type": "staking-events",
"id": "0d4c8b2a6e1f3a5c7e9b0d2f4a6c8e1b",
"attributes": {
"address": "0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9012345",
"slot": 15577216,
"block_number": 26337666,
"mined_at": "2026-11-04T00:03:35Z",
"events": [
{
"id": "4f9a…c21b",
"entity": "cl_reward",
"transaction_hash": "",
"block_number": 26337666,
"block_timestamp": 1793750615,
"deposit_address": "0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9012345",
"validator_index": 1048576,
"validator_pubkey": "0xa83c…9f1e",
"share": "1",
"amount": "2604000000000",
"validator_amount": "2604000000000",
"validator_balance": "32014211538000000000",
"address_role": "deposit_and_withdrawal",
"effective_balance": "32000000000000000000",
"principal": "32000000000000000000",
"accrued_rewards": "14211538000000000",
"reward_type": "consensus",
"epoch": 486787,
"withdrawal_address": "0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9012345",
"source": "beacon"
},
{
"id": "a17e…0b5d",
"entity": "el_reward",
"transaction_hash": "0x6d0f…a7c3",
"block_number": 26337666,
"block_timestamp": 1793750615,
"deposit_address": "0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9012345",
"validator_index": 1048577,
"validator_pubkey": "0xb5d2…44a0",
"share": "1",
"amount": "41250000000000000",
"validator_amount": "41250000000000000",
"validator_balance": "32009877120000000000",
"address_role": "deposit_and_withdrawal",
"to_address": "0x8f3a1c2b9d4e5f60718293a4b5c6d7e8f9012345",
"reward_type": "execution",
"method": "relay",
"relay": "ultrasound",
"source": "relay"
}
]
}
}slot, block_number and mined_at belong to the slot. events lists the events about this
address, as the staking pipeline sent them.
Fields found on every event:
| Field | Meaning |
|---|---|
id | the event's id, stable across resends |
entity | the event type, see the table below |
transaction_hash | the execution-layer transaction behind the event (deposit, request, MEV payment). "" for beacon-chain events, which have none |
deposit_address | the subscribed address the validator belongs to |
validator_index, validator_pubkey | the validator |
share | your share of the validator, currently always "1" |
amount | your part of the change, wei, can be negative |
validator_amount | the change for the whole validator, wei, can be negative |
validator_balance | the validator's beacon balance after the change, wei |
address_role | how your address is linked to the validator: deposit, withdrawal or deposit_and_withdrawal |
effective_balance, principal, accrued_rewards, pending_deposits | your stake after the slot, wei, when known. principal is what you deposited minus stake already returned. accrued_rewards is the balance above the principal: earned, not yet paid out, negative after penalties. pending_deposits is deposits paid but not yet credited. principal_stale: true means the principal might be out of date after a gap on our data provider's side |
source | where the data came from, for support questions |
Event types:
entity | What happened | Own fields |
|---|---|---|
cl_reward | consensus reward credited to the validator's balance, usually once per epoch. Negative means a penalty. A slashing is a negative cl_reward with anomaly: true and slashed: true | epoch, withdrawal_address, reward_type: "consensus", anomaly, slashed |
el_reward | priority fees and MEV for a block your validator proposed, paid to the fee recipient | to_address (fee recipient), reward_type: "execution", method (relay, builder_last_tx, titan_coinbase, vanilla), relay |
deposit_submitted | a deposit was sent to the deposit contract (new validator or top-up). Not credited yet | from_address, deposit_index, withdrawal_credentials, request_block_number |
deposit_credited | the beacon chain credited the deposit to the validator | |
status_change | the validator's status changed (activated, exiting, withdrawable, withdrawn) | from_status, to_status, exit_epoch, withdrawable_epoch |
exit_requested | an exit was requested | request_source (voluntary_exit or el_request), source_address, request_block_number |
withdrawal_requested | a partial withdrawal was requested (compounding validators) | source_address, request_block_number |
consolidation_requested | a request to merge one validator into another, or to switch to compounding | kind, role, source_pubkey, target_pubkey, source_address, request_block_number |
consolidation_out, consolidation_in | stake moved between two validators when a consolidation was processed | counterparty_index, counterparty_withdrawal_address, anomaly (outflow to a validator with a different withdrawal address) |
withdrawal_credentials_change | an old 0x00 validator got its withdrawal address set. This happens only once per validator | withdrawal_address |
partial_withdrawal and full_withdrawal events never show up in this list. They arrive as the
payout transfers described above.
New event types and new fields may appear without notice. Ignore what you don't recognise instead of failing on it.
Counting rewards without double counting
- Rewards =
cl_reward+el_reward. That's all of them. - A
partialpayout is not a new reward. It pays out rewards that were already reported ascl_rewardearlier. Count rewards from the accruals or from the payouts, never both. el_rewardis reported twice on purpose. The money reaches the fee recipient as an ordinary transaction, which you get as a normal delivery a few seconds after the block. Later, theel_rewardevent instaking-eventssays what that money was. It carries no transfer, so it doesn't change your balance. Link the two bytransaction_hash. For a block built without MEV (method: "vanilla"),transaction_hashis empty: the fees came in as the block's priority fees.- A deposit is the same: the 32 ETH leaving your address arrives as an ordinary delivery, and
deposit_submittedexplains it.
How the split works
Withdrawals pay out rewards first, then stake. In numbers:
reward_amount = min(amount, max(balance before the payout − principal, 0)), and
principal_amount is the rest.
- A
partialsweep from a standard (0x01) validator is almost always all reward. - On a
fullpayout,principal_amount+reward_amount=amount. If the validator exited with less than its principal (after penalties or slashing),principal_lossshows the difference. - When the principal isn't known, both split fields are
null. You still get the total inamountand in the transferquantity. We never guess the split.
How it differs from an ordinary subscription
- Validator payouts come only from the staking feed. They are not delivered twice. But they arrive later: today up to an hour after the block, because the data is published once the beacon chain finalizes it. A faster version (about 10 minutes) is planned. Everything else about your address still arrives within seconds.
- The payout looks different.
hashisslot_<slot>, notblock_<number>, and the transfer has astakingblock. - No retractions. Staking data is published after finality, so a staking delivery is never
followed by
deleted: true. - Order. Staking deliveries are ordered by
X-Lambda-Sequencelike everything else. A staking delivery can arrive after deliveries for later blocks, so don't assume chain order. Usemined_at_blockorslotif you need it.
Volume and cost
Each staking delivery is a regular delivery: 20 CU.
The main volume is cl_reward. At the moment it comes once per epoch (6.4 minutes), so an
address with active validators gets about 225 deliveries a day, around 4,500 CU, whether it
has one validator or a thousand. All the validators of one address share one delivery per slot.
Payouts and execution rewards add a few more.
Two of your addresses in the same slot means two deliveries. For example, if you subscribe both the deposit address and the withdrawal address of the same validators, you get the epoch rewards twice, once for each address. Subscribe one of them unless you need both.
Things to watch out for
Removing an address stops its staking data right away. That includes payouts for blocks that happened before the removal but hadn't been published yet (up to an hour). Adding it back doesn't bring them back. Remove an address only after its last validator has exited and been paid out.
The first minutes after you add an address. The staking pipeline picks up new addresses every
few minutes. Events from the gap are sent afterwards as catch-up deliveries, with hash ending
in _catchup_<n> because of the gap they may arrive after newer deliveries. In this short
window, one payout can arrive twice: once as a plain receipt on your address, then again in the
catch-up with your validator's details. If this matters to you, drop repeats by
withdrawal_index.
Payouts for someone else's validator. If a validator that belongs to another staker
withdraws to your address, you get the payout, but without the other staker's details:
deposit_address, share, amount and the split are null.
Big slots. If a slot has more events than fit in one delivery, the payouts still arrive in
full, and staking-events comes with events_omitted: true and omitted_event_count instead of
the event list. This can happen with thousands of validators on one address at an epoch boundary.
Amounts are strings in wei. They can be negative ("-1543000000" is a penalty). Use a
big-integer or decimal type; floats lose precision.
Disabling and suspension work as usual. Nothing is delivered or queued while the subscription is disabled or suspended, staking included.
Troubleshooting#
422 on create or add/remove, naming an address. It's a token contract or on the blocklist
(see Addresses you cannot subscribe to). Remove it and
send the call again; the rest will be accepted.
A transaction I expected didn't arrive. Check, in this order:
- the subscription is
disabled, or was at the time; - the transaction happened before the address's
activated_at(see List Addresses); - it moved only spam tokens and
include_spamis off; - the chain isn't in
chain_ids; - deliveries are suspended: look for a
subscription-noticesdelivery withnotice: suspended; - your server answered
4xx, or failed three attempts in a row.
The same transaction arrived twice. Delivery is at least once, so drop repeats by data.id.
Two deliveries with different data.attributes.address are not repeats: two of your addresses
were in the transaction.
Signature check fails. Verify the raw request bytes, not re-serialized JSON. Make sure you
prepend <t>.. Fetch the JWKS again if you don't know the X-Lambda-Key-Id.
A delivery came with deleted: true. A reorg removed that transaction. Undo what the first
delivery caused.
Staking: a validator payout came as a plain transfer, without a staking block. Either the
subscription was created without event_kinds: ["staking"], or it's on a chain other than
Ethereum.
Staking: no payout after a validator withdrawal I can see in an explorer. Wait an hour: payouts
come after finality. If it still isn't there, check that the address is in the subscription and
wasn't removed. If both are fine, contact support with the withdrawal_index.
Staking: getting 422 when changing filters on a staking subscription. filters is
replaced as a whole. Include "event_kinds": ["staking"] in what you send.