Once an account is registered, the deposit service handles everything from detection to settlement. This page explains what happens at each stage and how to monitor the process.
Deposit lifecycle
Detection
The service monitors registered accounts via chain indexer webhooks. When a token transfer is detected on a registered account, it goes through validation:
- The token and amount are checked against your deposit whitelist (if configured)
- The transfer is deduplicated by chain, transaction hash, account, and token
- If valid, the deposit enters the pipeline with status
processing
- If the token isn’t allowed or the amount is outside your configured min/max, the deposit is rejected (not bridged) and a
deposit-rejected webhook is sent after deposit-received
Bridging
The service submits a bridging intent to the Rhinestone Orchestrator, which routes the funds through the optimal settlement layer (Across, Relay, or others). If the primary layer fails, the service tries alternatives automatically.
Settlement
Tokens arrive on the target chain in the registered target token. If a recipient address was set at registration, funds are forwarded there. The service marks the deposit as completed and sends a bridge-complete webhook.
Deposit statuses
| Status | Meaning |
|---|
processing | Deposit detected, bridging in progress |
completed | Funds arrived on target chain |
failed | Bridging failed — may be retried automatically |
Retries
Automatic
Transient errors — bridge failures, session activation issues, and internal errors — are retried automatically. Configuration errors like unsupported tokens, insufficient balance, or unregistered accounts require manual resolution.
Manual
Force an immediate retry of all failed deposits for an account:
const response = await fetch(`${DEPOSIT_SERVICE_URL}/deposits/retry`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": API_KEY,
},
body: JSON.stringify({
address: accountAddress,
}),
});
const { deposits } = await response.json();
// [{ txHash: "0x...", chain: "eip155:8453" }, ...]
Error codes
When a deposit fails, the error code indicates what went wrong and whether the service will retry automatically.
Retryable
These are transient failures. The service retries automatically, or you can trigger a manual retry.
| Code | Description |
|---|
SESSION-2 | Session key activation failed |
BRIDGE-1 | Bridge submission failed |
BRIDGE-2 | No bridge quote available |
BRIDGE-3 | Bridge timed out |
BRIDGE-4 | Bridge provider failed |
BRIDGE-5 | Price deviation exceeded tolerance |
BRIDGE-7 | Bridge refunded |
BRIDGE-8 | Bridge cancelled |
BRIDGE-9 | Bridge rejected |
SWAP-1 | Post-bridge swap failed |
INTERNAL-1 | Unexpected service error |
Non-retryable
These indicate a configuration or input problem. Check account registration, deposit whitelist, and token support.
| Code | Description |
|---|
BALANCE-1 | Account balance too low for bridging |
BALANCE-2 | Account balance could not be read |
BALANCE-3 | Deposit amount above the configured maximum |
BALANCE-4 | Deposit amount below the configured minimum |
TOKEN-1 | Token not supported on this chain |
TOKEN-2 | Token account (Solana ATA) creation failed |
TOKEN-3 | Token not in deposit whitelist |
ACCOUNT-1 | Account not registered |
ACCOUNT-2 | Account (Solana Swig wallet) creation failed |
SESSION-1 | Smart session not found — resolved by re-registering the account |
TRANSFER-1 | Transfer execution failed |
BRIDGE-6 | Unsupported bridge route — no route available; the deposit is rejected, not retried |
Failed deposits with non-retryable errors will not be retried automatically. Resolve the underlying issue (e.g. update your deposit whitelist or register the account) before triggering a manual retry.
Whitelist and minimum rejections (BALANCE-4, BALANCE-3, TOKEN-3) are deposits the service deliberately won’t bridge per your configuration. These are surfaced via the deposit-rejected webhook — not bridge-failed — and no bridging is attempted. 
