> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rhinestone.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Project configuration

> Configure deposit whitelists, price tolerance, and minimum deposit value for your project.

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:

```ts theme={null}
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 [webhooks](/deposits/headless/processing-and-tracking/webhooks#configure-webhooks) and [fee sponsorship](/deposits/headless/fees/sponsorship#configure-sponsorship) in their dedicated guides.

## 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.

```ts theme={null}
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) |

<Warning>
  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.
</Warning>

If no whitelist is set, all [supported tokens](/deposits/overview/resources/supported-chains-and-tokens) are accepted with no amount restrictions.

Rejected deposits trigger a [`deposit-rejected`](/deposits/headless/processing-and-tracking/webhooks#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

Set the maximum allowed price deviation in basis points. Before bridging a deposit from an EVM chain, the service values the quote at market prices, with stablecoins at \$1: what the route delivers, plus the fees the user pays, may fall short of the deposit's value by at most this much. Deposits that exceed this threshold are rejected with error code `BRIDGE-5`.

```ts theme={null}
await fetch(`${DEPOSIT_SERVICE_URL}/setup`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    params: {
      maxPriceDeviationBps: 100, // 1% max deviation
    },
  }),
});
```

The default is `300` (3%) if not set. Tighten this where you need predictable output, such as stablecoin corridors; loosen it if you see rejections during volatile periods. Deposits worth less than \$5, and tokens without a market price, are not checked.

### Override the tolerance per token

Set `priceDeviationTokens` to give a source token its own tolerance. It replaces `maxPriceDeviationBps` for deposits of that token from that chain.

```ts theme={null}
await fetch(`${DEPOSIT_SERVICE_URL}/setup`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    params: {
      priceDeviationTokens: {
        "eip155:8453": [
          {
            token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC on Base
            maxPriceDeviationBps: 50,
          },
          {
            token: "0x4200000000000000000000000000000000000006", // WETH on Base
            maxPriceDeviationBps: 150,
          },
        ],
      },
    },
  }),
});
```

| Field                  | Type     | Description                                                                                          |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `token`                | `string` | Token address on the source chain; `0x0000000000000000000000000000000000000000` for the native token |
| `maxPriceDeviationBps` | `number` | Maximum allowed price deviation in basis points, `0`–`10000`                                         |

Each call replaces every stored override, so send the full set. Only EVM chains (`eip155:`) are accepted. HyperCore deposits are bridged from HyperEVM, so key them `eip155:999` with the token's HyperEVM address, not its HyperCore token ID.

## 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`](/deposits/headless/processing-and-tracking/webhooks#deposit-rejected) webhook is sent with error code `BALANCE-4` and no bridging is attempted.

```ts theme={null}
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 project configuration field, pass `null` for scalar fields or `{}` for object fields:

| To clear               | Pass   |
| ---------------------- | ------ |
| `depositWhitelist`     | `{}`   |
| `maxPriceDeviationBps` | `null` |
| `priceDeviationTokens` | `{}`   |
| `minDepositUsd`        | `null` |

## Put it all together

A single `/setup` call can configure these project settings at once:

```ts theme={null}
await fetch(`${DEPOSIT_SERVICE_URL}/setup`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    params: {
      depositWhitelist: {
        "eip155:8453": [
          {
            token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            minAmount: "1000000",
          },
        ],
        "eip155:42161": [
          { token: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" },
        ],
      },
      maxPriceDeviationBps: 150,
      minDepositUsd: 1,
    },
  }),
});
```