Skip to main content
Call POST /setup to configure how the deposit service handles your deposits. All fields are optional — configure what you need. Each call performs a partial update; omitted fields keep their current value. All examples below use these shared constants: 
const DEPOSIT_SERVICE_URL =
  "https://v1.orchestrator.rhinestone.dev/deposit-processor";
const API_KEY = "YOUR_RHINESTONE_API_KEY";

const headers = {
  "Content-Type": "application/json",
  "x-api-key": API_KEY,
};

​
Configure a webhook

Register a URL to receive notifications about deposit events. Optionally provide a secret for HMAC-SHA256 signature verification. 
await fetch(`${DEPOSIT_SERVICE_URL}/setup`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    params: {
      webhookUrl: "https://your-domain.com/notify",
      webhookSecret: "your-secret-key",
    },
  }),
});
When a webhookSecret is set, every webhook request includes an X-Webhook-Signature header you can verify. See status tracking for event types, payload format, and verification examples. Once your endpoint is live, fire a single fixture event with POST /webhooks/test to confirm signature handling and parsing before real deposits arrive. The envelope carries "test": true so receivers can filter it. Cover gas, bridging, and swap fees on behalf of your users so they receive the full deposit amount. Sponsorship is configured per source chain using CAIP-2 identifiers. Chains without explicit config default to no sponsorship. 
await fetch(`${DEPOSIT_SERVICE_URL}/setup`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    params: {
      sponsorship: {
        "eip155:8453": { gas: "all", bridging: "all" }, // Base
        "eip155:10": { gas: "all" }, // Optimism
        "eip155:42161": { gas: "deployed" }, // Arbitrum
      },
    },
  }),
});
See sponsorship for the full list of fee types, available values, and how sponsorship is resolved at processing time.

​
Restrict accepted deposits

Define a whitelist of accepted tokens per source chain. Deposits of unlisted tokens are silently ignored. You can also set minimum and maximum deposit amounts per token. 
await fetch(`${DEPOSIT_SERVICE_URL}/setup`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    params: {
      depositWhitelist: {
        "eip155:8453": [
          {
            token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
            minAmount: "1000000", // 1 USDC minimum
            maxAmount: "5000000000", // 5,000 USDC maximum
          },
        ],
        "eip155:42161": [
          { token: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" }, // USDC on Arbitrum, no limits
          {
            token: "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
            minAmount: "1000000",
          }, // USDT, $1 min
        ],
      },
    },
  }),
});
FieldTypeDescription
tokenstringToken address (0x-prefixed)
minAmountstringOptional. Minimum accepted amount in raw token units (inclusive)
maxAmountstringOptional. Maximum accepted amount in raw token units (inclusive)
If no whitelist is set, all supported tokens are accepted with no amount restrictions. Rejected deposits trigger a deposit-rejected webhook — not bridge-failed — with error code TOKEN-3 (token not allowed), BALANCE-3 (amount above the configured maximum), or BALANCE-4 (amount below the configured minimum).

​
Set price deviation tolerance

For stablecoin-to-stablecoin bridges, set the maximum allowed price deviation in basis points. Deposits that exceed this threshold are rejected with error code BRIDGE-5. 
await fetch(`${DEPOSIT_SERVICE_URL}/setup`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    params: {
      maxPriceDeviationBps: 100, // 1% max deviation
    },
  }),
});
The default is 200 (2%) if not set. Tighten this for high-value stablecoin corridors; loosen it if you see rejections during volatile periods.

​
Set a minimum deposit value

Set a per-client minimum deposit value in USD, applied across all tokens and source chains. Deposits priced below it are rejected — a deposit-rejected webhook is sent with error code BALANCE-4 and no bridging is attempted. 
await fetch(`${DEPOSIT_SERVICE_URL}/setup`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    params: {
      minDepositUsd: 1, // reject deposits worth less than $1
    },
  }),
});
minDepositUsd is a non-negative number (USD). This is a per-client override; a platform-wide minimum floor also applies and is not client-configurable.

​
Clear a configuration field

Each /setup call is a partial update. To explicitly clear a field, pass null for string fields or {} for object fields:
To clearPass
webhookUrlnull
webhookSecretnull
sponsorship{}
depositWhitelist{}
maxPriceDeviationBpsnull
minDepositUsdnull

​
Put it all together

A single /setup call configuring everything at once: 
await fetch(`${DEPOSIT_SERVICE_URL}/setup`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    params: {
      webhookUrl: "https://your-domain.com/notify",
      webhookSecret: "your-secret-key",
      sponsorship: {
        "eip155:8453": { gas: "all", bridging: "all" },
        "eip155:10": { gas: "all" },
      },
      depositWhitelist: {
        "eip155:8453": [
          {
            token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            minAmount: "1000000",
          },
        ],
        "eip155:42161": [
          { token: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" },
        ],
      },
      maxPriceDeviationBps: 150,
      minDepositUsd: 1,
    },
  }),
});