Initial setup - Rhinestone

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
        ],
      },
    },
  }),
});

Field	Type	Description
`token`	`string`	Token identifier, as `GET /chains` reports it in `depositTokens`
`minAmount`	`string`	Optional. Minimum accepted amount in raw token units (inclusive)
`maxAmount`	`string`	Optional. Maximum accepted amount in raw token units (inclusive)

Take token from a chain’s depositTokens in GET /chains, not from supportedTokens. The two answer different questions — what you can deposit from a chain, and what can be delivered to it — and on HyperCore they are different identifiers for the same asset. Everywhere else they match.A whitelist keyed on an identifier deposits are not matched on rejects every deposit with TOKEN-3, and /setup still returns 200, so the only symptom is that nothing arrives. minAmount / maxAmount are in the units of the identifier you used — for HyperCore USDC that is 8 decimals, not 6.

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 clear	Pass
`webhookUrl`	`null`
`webhookSecret`	`null`
`sponsorship`	`{}`
`depositWhitelist`	`{}`
`maxPriceDeviationBps`	`null`
`minDepositUsd`	`null`

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,
    },
  }),
});

​Configure a webhook

​Sponsor fees

​Restrict accepted deposits

​Set price deviation tolerance

​Set a minimum deposit value

​Clear a configuration field

​Put it all together