Webhooks Guide

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:

  1. Log in to the dRPC dashboard, open API Keys and select your key.
  2. Copy the base URL from the Data & Wallet API card. It looks like https://lb.drpc.live/lambda/<YOUR_API_TOKEN>.
  3. Webhook endpoints are under /v1/webhooks/subscriptions on that base URL:
https://lb.drpc.live/lambda/<YOUR_API_TOKEN>/v1/webhooks/subscriptions

There is no per-chain URL. A subscription picks its chains in chain_ids.

Pricing

ActionCU
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

LimitValue
Subscriptions per account50
Addresses per subscription10,000
Addresses per account, all subscriptions together100,000 (can be raised on request)
Addresses per call (create, add/remove)100
Time your server has to answer a delivery10 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: 42

The 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.json

Take 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 False

Verify 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"
}
FieldMeaning
statusenabled or disabled. Only enabled subscriptions get deliveries
chain_idslowercase chain slugs. [] means every supported chain, including future ones
filterssee below
address_counthow 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, with flags.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 fieldRequiredRules
callback_urlyeshttps:// only, on a public host. Private and reserved IPs, localhost and internal suffixes are rejected
addressesyes1 to 100 per call; add the rest with Add / Remove Addresses. Hex addresses are lowercased
chain_idsnoup to 50 slugs. Omit it or send [] for all chains
filtersno{}, {"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 paramMeaning
limit1 to 1000, default 100
cursorthe 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:

  • filters replaces 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 every filters you 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

HeaderExampleMeaning
X-Lambda-Signaturet=1790001557, v1=<base64>Ed25519 signature over <t>.<body>
X-Lambda-Key-Idprimarywhich JWKS key signed it
X-Lambda-Sequence42a 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
      }
    }
  ]
}
FieldMeaning
data.idthe delivery id. Use it to drop duplicates
data.attributes.addressthe watched address this delivery is about (null on a subscription notice)
data.relationships.subscription.idthe subscription
included[0].idtransaction id, the same in every delivery of this transaction
attributes.operation_typeLambda'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
quantityint is the raw amount as a string, plus decimals, a float, and numeric, the exact amount as a decimal string
price, valueUSD price and value at delivery time; null when we don't have a price
attributes.feethe gas paid, only when your address paid it; null otherwise
attributes.flags.is_spamtrue 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_metadatathe contract and method called, when we know them
attributes.events_omittedtrue when the transaction was too large to ship with its transfers. Fetch it by hash from the Transactions API
relationships.chain.idchain 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

Acknowledginganswer 2xx within 10 seconds
Retriesa 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"
Duplicatespossible, delivery is at least once. Drop repeats by data.id
Ordernew deliveries of one subscription go out in X-Lambda-Sequence order. There is no order across chains, and notices can overtake waiting deliveries
Latencya few seconds after the block. Staking feed deliveries are slower, see below
Charging20 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_ids must be empty or include ethereum. Otherwise 422.
  • 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 transactions object, if a validator payout landed on the address in that slot;
  • a staking-events object, 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:

  • hash is not a transaction hash. A withdrawal has no transaction, so we use the slot: slot_<slot>, or slot_<slot>_catchup_<n> for a catch-up. mined_at_block is the execution block of that slot.
  • fee, sent_from, sent_to and each transfer's sender are null.
  • There is one transfer per withdrawal. If several of your validators were paid in the same slot, they are all in one delivery.
  • quantity is 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:

FieldMeaning
kindpartial: 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_pubkeythe validator that paid
withdrawal_indexthe beacon chain's withdrawal number. Unique, so it is a good key for deduplication
deposit_addressthe subscribed address this validator belongs to. null if the money landed on your address but the validator belongs to someone else (see below)
shareyour share of the validator as a fraction, for example "1" or "3/4". Currently always "1"
amountyour part of the payout in wei: the payout × share
reward_amount, principal_amountthe split of amount into reward and returned stake, in wei. null when the principal isn't known (see How the split works)
principal_losson 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:

FieldMeaning
idthe event's id, stable across resends
entitythe event type, see the table below
transaction_hashthe execution-layer transaction behind the event (deposit, request, MEV payment). "" for beacon-chain events, which have none
deposit_addressthe subscribed address the validator belongs to
validator_index, validator_pubkeythe validator
shareyour share of the validator, currently always "1"
amountyour part of the change, wei, can be negative
validator_amountthe change for the whole validator, wei, can be negative
validator_balancethe validator's beacon balance after the change, wei
address_rolehow your address is linked to the validator: deposit, withdrawal or deposit_and_withdrawal
effective_balance, principal, accrued_rewards, pending_depositsyour 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
sourcewhere the data came from, for support questions

Event types:

entityWhat happenedOwn fields
cl_rewardconsensus 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: trueepoch, withdrawal_address, reward_type: "consensus", anomaly, slashed
el_rewardpriority fees and MEV for a block your validator proposed, paid to the fee recipientto_address (fee recipient), reward_type: "execution", method (relay, builder_last_tx, titan_coinbase, vanilla), relay
deposit_submitteda deposit was sent to the deposit contract (new validator or top-up). Not credited yetfrom_address, deposit_index, withdrawal_credentials, request_block_number
deposit_creditedthe beacon chain credited the deposit to the validator
status_changethe validator's status changed (activated, exiting, withdrawable, withdrawn)from_status, to_status, exit_epoch, withdrawable_epoch
exit_requestedan exit was requestedrequest_source (voluntary_exit or el_request), source_address, request_block_number
withdrawal_requesteda partial withdrawal was requested (compounding validators)source_address, request_block_number
consolidation_requesteda request to merge one validator into another, or to switch to compoundingkind, role, source_pubkey, target_pubkey, source_address, request_block_number
consolidation_out, consolidation_instake moved between two validators when a consolidation was processedcounterparty_index, counterparty_withdrawal_address, anomaly (outflow to a validator with a different withdrawal address)
withdrawal_credentials_changean old 0x00 validator got its withdrawal address set. This happens only once per validatorwithdrawal_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 partial payout is not a new reward. It pays out rewards that were already reported as cl_reward earlier. Count rewards from the accruals or from the payouts, never both.
  • el_reward is 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, the el_reward event in staking-events says what that money was. It carries no transfer, so it doesn't change your balance. Link the two by transaction_hash. For a block built without MEV (method: "vanilla"), transaction_hash is 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_submitted explains 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 partial sweep from a standard (0x01) validator is almost always all reward.
  • On a full payout, principal_amount + reward_amount = amount. If the validator exited with less than its principal (after penalties or slashing), principal_loss shows the difference.
  • When the principal isn't known, both split fields are null. You still get the total in amount and in the transfer quantity. 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. hash is slot_<slot>, not block_<number>, and the transfer has a staking block.
  • 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-Sequence like everything else. A staking delivery can arrive after deliveries for later blocks, so don't assume chain order. Use mined_at_block or slot if 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_spam is off;
  • the chain isn't in chain_ids;
  • deliveries are suspended: look for a subscription-notices delivery with notice: 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.