Status tracking - Rhinestone

There are two ways to track a deposit through the processing pipeline:

Polling — query the GET /deposits endpoint filtered by transaction hash. Simple and stateless.
Webhooks — receive push notifications as deposits move through each stage. Real-time and event-driven.

Use whichever fits your architecture. Many integrations combine both: webhooks for real-time updates, polling as a fallback or for on-demand status checks.

Polling

Query the GET /deposits endpoint with the txHash parameter to look up a deposit by its source transaction hash.

const DEPOSIT_SERVICE_URL =
    "https://v1.orchestrator.rhinestone.dev/deposit-processor";
const API_KEY = "YOUR_RHINESTONE_API_KEY";

const txHash = "0xabc123...";

const response = await fetch(
    `${DEPOSIT_SERVICE_URL}/deposits?txHash=${txHash}`,
    {
        headers: { "x-api-key": API_KEY },
    },
);

const { deposits } = await response.json();

Response

Each item in the deposits array has the following shape:

Field	Type	Description
`id`	`string`	Unique deposit identifier
`chain`	`string`	Source chain (CAIP-2)
`txHash`	`string`	Source transaction hash
`token`	`string`	Deposit token address
`amount`	`string`	Deposit amount (raw token units)
`sender`	`string`	Sender address
`account`	`string`	Registered account address
`targetChain`	`string`	Destination chain (CAIP-2)
`targetToken`	`string`	Destination token address
`status`	`string`	In-progress: `"processing"`, `"expecting_refund"`. Terminal: `"completed"`, `"failed"`, `"rejected"`, `"refunded"`, `"ignored"`
`sourceTxHash`	`string \| null`	Bridge source transaction hash
`destinationTxHash`	`string \| null`	Bridge destination transaction hash
`sourceAmount`	`string \| null`	Bridge source amount
`destinationAmount`	`string \| null`	Bridge destination amount
`errorCode`	`string \| null`	Error code if the deposit failed
`createdAt`	`string`	ISO 8601 timestamp of when the deposit was detected
`completedAt`	`string \| null`	ISO 8601 timestamp of when the deposit completed
`retryable`	`boolean`	Whether a failed deposit can be retried — `false` for non-retryable errors and policy rejections
`isSpam`	`boolean`	Flagged as spam (token has no known price); omitted from results unless you pass `includeSpam=true`

Polling loop

Poll until the deposit reaches a terminal status (completed, failed, rejected, refunded, or ignored):

const TERMINAL = new Set(["completed", "failed", "rejected", "refunded", "ignored"]);

async function waitForDeposit(txHash: string): Promise<void> {
    const url = `${DEPOSIT_SERVICE_URL}/deposits?txHash=${txHash}`;
    const headers = { "x-api-key": API_KEY };

    while (true) {
        const response = await fetch(url, { headers });
        const { deposits } = await response.json();
        const deposit = deposits[0];

        if (!deposit) {
            // Deposit not yet indexed — wait and retry
            await new Promise((r) => setTimeout(r, 1_000));
            continue;
        }

        if (TERMINAL.has(deposit.status)) {
            // `rejected` carries an errorCode (whitelist/minimum); see deposit-rejected
            console.log("Deposit settled:", deposit.status, deposit.errorCode ?? deposit.destinationTxHash);
            return;
        }

        // Still in progress (`processing` / `expecting_refund`) — poll again
        await new Promise((r) => setTimeout(r, 1_000));
    }
}

A 1-second interval works well for most use cases. Most deposits complete within seconds.

Webhooks

The deposit service sends webhook notifications to your configured endpoint as deposits move through the processing pipeline. All webhooks are POST requests with Content-Type: application/json. Configure your webhook URL and optional secret via the POST /setup endpoint.

Payload envelope

Every webhook request body follows the same envelope structure:

{
  "version": "1.0",
  "type": "<event-type>",
  "eventId": "12345",
  "time": "2025-01-15T12:00:00.000Z",
  "data": { ... }
}

Field	Type	Description
`version`	`string`	Protocol version. Currently `"1.0"`
`type`	`string`	Event type identifier
`eventId`	`string`	Stable identifier for this delivery. Use it as the canonical dedupe key
`time`	`string`	ISO 8601 timestamp of when the event was sent
`test`	`boolean \| undefined`	Present and `true` only for events dispatched via the test endpoint
`data`	`object`	Event-specific payload (see below)

Event types

Type	Trigger
`deposit-received`	Token transfer detected on a registered account
`deposit-rejected`	Detected deposit will not be bridged — deposit whitelist or minimum violation
`bridge-started`	Bridging intent created and submitted to the Orchestrator
`bridge-complete`	Tokens arrived on the target chain
`bridge-delayed`	Bridge provider did not fill within the expected window; a refund is expected
`bridge-failed`	Bridging failed
`deposit-refunded`	Deposit funds returned to a recipient on the source chain
`error`	Unexpected error while processing a deposit (the settlement catch-all)

`deposit-received`

Sent when an incoming token transfer is detected on a registered account.

Field	Type	Description
`chain`	`string`	Source chain (CAIP-2, e.g. `"eip155:8453"`)
`token`	`string`	Token address
`amount`	`string`	Deposit amount in raw token units
`account`	`string`	Account address
`transactionHash`	`string`	Deposit transaction hash
`sender`	`string`	Sender address

{
    "version": "1.0",
    "type": "deposit-received",
    "eventId": "12345",
    "time": "2025-01-15T12:00:00.000Z",
    "data": {
        "chain": "eip155:8453",
        "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "amount": "1000000",
        "account": "0x1234567890abcdef1234567890abcdef12345678",
        "transactionHash": "0xabc123...",
        "sender": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
    }
}

`deposit-rejected`

Sent when a detected deposit will not be bridged because it violates the account’s deposit whitelist — the token isn’t allowed, or the amount is outside the configured minimum/maximum. It always follows a deposit-received event for the same deposit and is terminal: no bridging is attempted and there is no retry. This is a deliberate rejection, not a processing failure — use it to record the outcome on your side. See error codes for the full list.

Field	Type	Description
`errorCode`	`string`	Reason — `"BALANCE-4"` (below minimum), `"BALANCE-3"` (above maximum), or `"TOKEN-3"` (token not allowed)
`account`	`string`	Account address
`message`	`string \| undefined`	Human-readable explanation
`limits.minAmount`	`string \| undefined`	Configured minimum in raw token units — present for `BALANCE-4` when the rejection is a per-token whitelist minimum
`limits.minAmountUsd`	`string \| undefined`	Configured minimum as a USD value — present for `BALANCE-4` when the rejection is your per-client USD floor (a `BALANCE-4` carries `minAmount` or `minAmountUsd`, not both)
`limits.maxAmount`	`string \| undefined`	Configured maximum in raw token units — present for `BALANCE-3`
`deposit.transactionHash`	`string`	Deposit transaction hash
`deposit.chain`	`string`	Deposit chain (CAIP-2)
`deposit.token`	`string`	Deposit token address
`deposit.amount`	`string`	Actual deposited amount in raw token units
`deposit.sender`	`string`	Sender address

Compare deposit.amount (what was deposited) against limits (the configured bound) to surface the shortfall or overage to your users.

{
    "version": "1.0",
    "type": "deposit-rejected",
    "eventId": "12347",
    "time": "2025-01-15T12:00:01.000Z",
    "data": {
        "errorCode": "BALANCE-4",
        "account": "0x1234567890abcdef1234567890abcdef12345678",
        "message": "Amount 500000 is below configured minimum 1000000",
        "limits": {
            "minAmount": "1000000"
        },
        "deposit": {
            "transactionHash": "0xabc123...",
            "chain": "eip155:8453",
            "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
            "amount": "500000",
            "sender": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
        }
    }
}

`bridge-started`

Sent when a bridging intent is created and submitted to the Orchestrator.

Field	Type	Description
`source.chain`	`string`	Source chain (CAIP-2)
`source.asset`	`string`	Source asset address
`source.amount`	`string`	Source amount
`destination.chain`	`string`	Destination chain (CAIP-2)
`destination.asset`	`string`	Destination asset address
`destination.amount`	`string`	Destination amount
`account`	`string`	Account address
`deposit.transactionHash`	`string`	Original deposit transaction hash
`deposit.chain`	`string`	Deposit chain (CAIP-2)
`deposit.asset`	`string`	Deposit asset address
`deposit.amount`	`string`	Deposit amount
`deposit.sender`	`string`	Sender address
`settlementLayer`	`string`	Settlement layer used (e.g. `"layerzero"`)
`estimatedFillTime.seconds`	`number \| undefined`	Estimated time to fill, in seconds, when the route provides one

`bridge-complete`

Sent when tokens have arrived on the target chain.

Field	Type	Description
`deposit.transactionHash`	`string`	Original deposit transaction hash
`deposit.chain`	`string`	Deposit chain (CAIP-2)
`deposit.asset`	`string`	Deposit asset address
`deposit.amount`	`string`	Deposit amount
`deposit.sender`	`string`	Sender address
`source.transactionHash`	`string`	Source chain claim transaction hash
`source.chain`	`string`	Source chain (CAIP-2)
`source.amount`	`string`	Source amount
`source.asset`	`string`	Source asset address
`destination.transactionHash`	`string`	Destination chain transaction hash
`destination.chain`	`string`	Destination chain (CAIP-2)
`destination.amount`	`string`	Destination amount
`destination.asset`	`string`	Destination asset address
`destination.logIndex`	`number \| undefined`	Log index of the destination transfer, when available
`account`	`string`	Account address
`settlementLayer`	`string \| undefined`	Settlement layer used

{
    "version": "1.0",
    "type": "bridge-complete",
    "eventId": "12346",
    "time": "2025-01-15T12:01:30.000Z",
    "data": {
        "deposit": {
            "transactionHash": "0xabc123...",
            "chain": "eip155:8453",
            "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
            "amount": "1000000",
            "sender": "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
        },
        "source": {
            "transactionHash": "0xdef456...",
            "chain": "eip155:8453",
            "amount": "1000000",
            "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
        },
        "destination": {
            "transactionHash": "0x789ghi...",
            "chain": "eip155:42161",
            "amount": "990000",
            "asset": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
            "logIndex": 5
        },
        "account": "0x1234567890abcdef1234567890abcdef12345678"
    }
}

`bridge-delayed`

Sent when the bridge provider has not filled the intent within the expected window. A refund is expected on the source chain; the subsequent deposit-refunded event confirms the funds returned.

Field	Type	Description
`reason`	`string`	Human-readable explanation of the delay
`estimatedDelayTime.seconds`	`number \| undefined`	Additional time the refund is expected to take, when available
`account`	`string`	Account address
`deposit.transactionHash`	`string`	Deposit transaction hash
`deposit.chain`	`string`	Deposit chain (CAIP-2)
`deposit.token`	`string`	Deposit token address
`deposit.amount`	`string`	Deposit amount
`deposit.sender`	`string`	Sender address

`bridge-failed`

Sent when a bridging operation fails. See error codes for the full list and retry behavior.

Field	Type	Description
`errorCode`	`string`	Error code (e.g. `"BRIDGE-1"`)
`account`	`string`	Account address
`message`	`string \| undefined`	Human-readable error description
`deposit.transactionHash`	`string`	Deposit transaction hash
`deposit.chain`	`string`	Deposit chain (CAIP-2)
`deposit.token`	`string`	Deposit token address
`deposit.amount`	`string`	Deposit amount
`deposit.sender`	`string`	Sender address

`deposit-refunded`

Sent when funds from a deposit are returned to a recipient on the source chain. Typically follows a bridge-delayed event.

Field	Type	Description
`account`	`string`	Account address
`deposit.transactionHash`	`string`	Original deposit transaction hash
`deposit.chain`	`string`	Deposit chain (CAIP-2)
`deposit.asset`	`string`	Deposit asset address
`deposit.amount`	`string`	Deposit amount
`deposit.sender`	`string`	Sender address
`refund.transactionHash`	`string`	Refund transaction hash
`refund.chain`	`string`	Refund chain (CAIP-2)
`refund.asset`	`string`	Refund asset address
`refund.amount`	`string`	Refund amount
`refund.recipient`	`string`	Address that received the refund

`error`

Sent when an unexpected, unhandled error occurs while processing a deposit — the catch-all in the settlement pipeline. It is not part of the normal lifecycle ordering and may arrive at any point. It carries whatever deposit / account / intent context was available at the point of failure; the optional fields are present only when that context was known.

Field	Type	Description
`error.message`	`string`	Error message
`error.stack`	`string \| undefined`	Stack trace, when available
`error.cause`	`unknown \| undefined`	Underlying cause, when available
`intentId`	`string \| undefined`	Bridging intent id, when the failure occurred after the intent was created
`account`	`string \| undefined`	Account address, when known
`deposit.transactionHash`	`string`	Deposit transaction hash (the `deposit` object is present only when the deposit was known)
`deposit.chain`	`string`	Deposit chain (CAIP-2)
`deposit.token`	`string`	Deposit token address
`deposit.amount`	`string`	Deposit amount in raw token units
`deposit.sender`	`string`	Sender address

Treat error as a signal that a deposit needs manual attention. Correlate on deposit.transactionHash / intentId and reconcile by polling GET /deposits.

Signature verification

If you provided a webhookSecret during setup, every webhook request includes an X-Webhook-Signature header:

X-Webhook-Signature: sha256=<hex-encoded-signature>

The signature is an HMAC-SHA256 hash computed over the raw JSON request body using your secret. To verify:

Read the raw request body as a string (before JSON parsing)
Compute the HMAC-SHA256 of the raw body using your webhook secret
Compare the result with the value in the X-Webhook-Signature header (strip the sha256= prefix)
Use a constant-time comparison to prevent timing attacks

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhookSignature(
    rawBody: string,
    signatureHeader: string,
    secret: string,
): boolean {
    const expected =
        "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
    return (
        signatureHeader.length === expected.length &&
        timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))
    );
}

Always verify against the raw request body string, not a re-serialized version of the parsed JSON. Re-serialization may change key order or whitespace, which will produce a different signature.

Delivery behavior

Retries — failed deliveries are retried multiple times before the event is marked failed. Events that exhaust their retries can still be replayed on demand via POST /webhooks/events/{id}/resend, which reuses the original eventId.
Ordering — events for a single deposit are sent in lifecycle order: deposit-received → bridge-started → bridge-complete when it proceeds, or deposit-received → deposit-rejected when it won’t be bridged. There is no global ordering guarantee across deposits.
URL validation — the webhook URL must use HTTPS and must not target internal or private network addresses.
Idempotency — use eventId from the envelope as the canonical dedupe key.

Backfilling missed events

If your receiver was offline or rejected events, replay them through the events API. Every dispatched webhook is persisted regardless of delivery outcome. List events delivered (or attempted) to your URL, newest first:

const response = await fetch(
    `${DEPOSIT_SERVICE_URL}/webhooks/events?since=2025-01-15T00:00:00Z`,
    { headers: { "x-api-key": API_KEY } },
);
const { events, nextCursor } = await response.json();

Re-send a stored event to your URL — the original eventId is reused so dedupe still holds:

await fetch(`${DEPOSIT_SERVICE_URL}/webhooks/events/${eventId}/resend`, {
    method: "POST",
    headers: { "x-api-key": API_KEY },
});

For more details, see the API reference for GET /webhooks/events and POST /webhooks/events/{id}/resend.

Conventions

EVM addresses and token addresses are lowercase. Non-EVM addresses (Solana, Tron) preserve their original case.
All amounts are strings (raw token units, not human-readable).
Chains use CAIP-2 identifiers (e.g. "eip155:8453" for Base).

​Polling

​Response

​Polling loop

​Webhooks

​Payload envelope

​Event types

​deposit-received

​deposit-rejected

​bridge-started

​bridge-complete

​bridge-delayed

​bridge-failed

​deposit-refunded

​error

​Signature verification

​Delivery behavior

​Backfilling missed events

​Conventions

Polling

Response

Polling loop

Webhooks

Payload envelope

Event types

`deposit-received`

`deposit-rejected`

`bridge-started`

`bridge-complete`

`bridge-delayed`

`bridge-failed`

`deposit-refunded`

`error`

Signature verification

Delivery behavior

Backfilling missed events

Conventions