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

# Backend

> The widget needs a proxy holding your Rhinestone API key. Write one, or deploy Rhinestone's.

The widget runs in the browser, so it can't hold your Rhinestone API key — the key authorizes writes against your project, from registering accounts to spending sponsorship. Every request the modal makes goes to a proxy **you** run, which attaches the key and forwards to the deposit processor.

All three modals take it as a required `backendUrl`. There is no default — point it at a proxy you run, on your own key.

Two ways to get one:

* **Deploy Rhinestone's.** Open source and configurable — see [deploy the Rhinestone proxy](#deploy-the-rhinestone-proxy).
* **Write your own.** A route table and a header — see [minimal proxy](#minimal-proxy).

<Warning>
  If you have a deployed integration that never set `backendUrl`, it is running on
  Rhinestone's API key rather than yours. Point it at your own proxy.
</Warning>

## Deploy the Rhinestone proxy

[`rhinestonewtf/deposit-widget-proxy`](https://github.com/rhinestonewtf/deposit-widget-proxy) is the proxy Rhinestone runs, packaged so you can deploy it as-is. It covers every route in the [table below](#required-routes), and adds [regional payment methods](#regional-payment-methods) — which a hand-written proxy can't do, since resolving the user's country needs the edge that actually sees them.

It needs one variable — your API key:

```bash theme={null}
git clone https://github.com/rhinestonewtf/deposit-widget-proxy
cd deposit-widget-proxy
docker build -t deposit-widget-proxy .
docker run -p 4000:4000 -e RHINESTONE_API_KEY=your-key deposit-widget-proxy
```

Point `backendUrl` at it and check `GET /health`. Everything else is optional and documented in the repository's [README](https://github.com/rhinestonewtf/deposit-widget-proxy#configuration):

| Variable                                                              | Purpose                                                           |
| --------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `RHINESTONE_API_KEY`                                                  | Attached as `x-api-key` upstream. The process exits if it's unset |
| `DEPOSIT_SERVICE_URL`                                                 | The upstream processor. Defaults to production                    |
| `TRUSTED_COUNTRY_HEADER`, `TRUSTED_PROXY_HOPS`, `TRUSTED_PROXY_CIDRS` | [Regional payment methods](#regional-payment-methods)             |

## Minimal proxy

A proxy is an explicit route table plus a header. The allowlist is the security boundary — see the warning below.

```ts theme={null}
import { Hono } from "hono";
import { cors } from "hono/cors";

const UPSTREAM = "https://v1.orchestrator.rhinestone.dev/deposit-processor";
const MODAL_VERSION_HEADER = "x-deposit-modal-version";

// Every route the modal calls, and nothing else. `:param` segments are matched
// by Hono, so a request can only reach a shape you listed here.
const ROUTES: [method: "get" | "post", path: string][] = [
  ["post", "/register-managed"],
  ["post", "/quotes/preview"],
  ["get", "/check/:address"],
  ["get", "/portfolio/:address"],
  ["get", "/portfolio/solana/:address"],
  ["get", "/deposits"],
  ["get", "/liquidity"],
  ["get", "/prices"],
  ["get", "/setup"],
  ["get", "/qr/tokens"],
  ["post", "/polymarket/withdraw"],
  // Only needed if you enable `assetMigrations` for a DeFi protocol (e.g. Aave).
  // Both are served by a read-scoped key: `unwind` writes nothing and returns an
  // unsigned transaction only the position holder's wallet can execute.
  ["get", "/positions/:address"],
  ["post", "/positions/:address/unwind"],
  ["post", "/onramp/swapped/widget-url"],
  ["post", "/onramp/swapped/connect-url"],
  ["get", "/onramp/swapped/connect-exchanges"],
  ["get", "/onramp/swapped/payment-methods"],
  ["get", "/onramp/swapped/status/:smartAccount"],
  // Safe to forward: the user's signature in the body is the authorization, so
  // your API key alone can't move funds through it. See below.
  ["post", "/deposits/recover"],
  // Add ["post", "/safe/withdraw"] only if your onSendTransaction relays through
  // it. Do NOT add /deposits/refund here — see below.
];

const app = new Hono();
app.use("*", cors());

for (const [method, path] of ROUTES) {
  app[method](path, async (c) => {
    const url = new URL(c.req.url);

    // A fresh header set, never the incoming one: the browser must not be able
    // to set `x-api-key` itself.
    const headers: Record<string, string> = {
      "Content-Type": "application/json",
      "x-api-key": process.env.RHINESTONE_API_KEY!,
    };
    const modalVersion = c.req.header(MODAL_VERSION_HEADER);
    if (modalVersion) headers[MODAL_VERSION_HEADER] = modalVersion;

    const res = await fetch(`${UPSTREAM}${url.pathname}${url.search}`, {
      method: c.req.method,
      headers,
      body: method === "get" ? undefined : await c.req.text(),
    });
    return new Response(res.body, { status: res.status });
  });
}

export default app;
```

<Warning>
  Do **not** replace that loop with a wildcard passthrough (`app.all("/*", …)`). The
  proxy attaches your API key to whatever reaches it, so a wildcard hands the browser
  every write on the upstream — including `POST /setup`, which rotates your webhook
  secret and sponsorship config. The route list is what stops that.
</Warning>

### Recovery can be forwarded; refunds cannot

These two look alike and differ in exactly one way: where the authorization comes
from.

`POST /deposits/recover` carries a signature from the deposit's `recipient`, covering
which deposit and which destination. The service verifies it before moving anything,
so your API key on its own achieves nothing here — which is what makes it safe to
forward like any other route. See
[claim modal](/deposits/widget/claim-modal#how-authorization-works).

`POST /deposits/refund` carries no such proof. Every route in that loop passes the
browser's body through with your API key attached, so forwarding this one would let
anyone return any of your recoverable deposits to an address they chose. A proxy
authenticates nobody, so it cannot be the thing that decides.

Most apps need only the recover route. If some of your recipients genuinely cannot
sign, authorize a refund in your own backend with
[`createRefundHandler`](/deposits/widget/claim-modal#when-the-user-cant-sign), which
checks the deposit belongs to the caller before spending the key, and call the
processor directly.

## Required routes

Missing a route doesn't degrade the flow — the request 404s and that part of the modal stops working.

| Method | Route                                  | Used for                                                                                                                                                                                                    |
| ------ | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` | `/register-managed`                    | Registering the deposit account. **Required**                                                                                                                                                               |
| `POST` | `/quotes/preview`                      | Indicative fee/time quote on the review screen                                                                                                                                                              |
| `GET`  | `/check/:address`                      | Registration + target lookup                                                                                                                                                                                |
| `GET`  | `/portfolio/:address`                  | EVM balances                                                                                                                                                                                                |
| `GET`  | `/portfolio/solana/:address`           | Solana balances                                                                                                                                                                                             |
| `GET`  | `/deposits`                            | Deposit status + history                                                                                                                                                                                    |
| `GET`  | `/liquidity`                           | Route liquidity check                                                                                                                                                                                       |
| `GET`  | `/prices`                              | USD pricing                                                                                                                                                                                                 |
| `GET`  | `/setup`                               | Your client config (source-token allowlist, minimums)                                                                                                                                                       |
| `GET`  | `/qr/tokens`                           | Suggested source tokens for the QR flow, filtered to what your config accepts                                                                                                                               |
| `GET`  | `/onramp/swapped/payment-methods`      | Fiat methods for the user's region. See [regional payment methods](#regional-payment-methods)                                                                                                               |
| `POST` | `/deposits/recover`                    | [Self-service recovery](/deposits/widget/claim-modal), authorized by the user's signature                                                                                                                   |
| `GET`  | `/positions/:address`                  | DeFi positions the user can migrate. Only for [asset migrations](/deposits/widget/asset-migrations)                                                                                                         |
| `POST` | `/positions/:address/unwind`           | Builds the unsigned exit transaction for one position. Only for asset migrations                                                                                                                            |
| `POST` | `/polymarket/withdraw`                 | Polymarket withdrawals                                                                                                                                                                                      |
| `POST` | `/onramp/swapped/widget-url`           | Fiat on-ramp                                                                                                                                                                                                |
| `POST` | `/onramp/swapped/connect-url`          | Exchange connect                                                                                                                                                                                            |
| `GET`  | `/onramp/swapped/connect-exchanges`    | Exchange list                                                                                                                                                                                               |
| `GET`  | `/onramp/swapped/status/:smartAccount` | On-ramp order status                                                                                                                                                                                        |
| `POST` | `/safe/withdraw`                       | Relaying a signed Safe transfer with sponsored gas. **Not called by the modal** — proxy it only if your own [`onSendTransaction`](/deposits/widget/withdraw-modal#executing-the-transfer) relays through it |

<Warning>
  Proxy `GET /setup` only, never `POST /setup`. The POST is an admin write — it rotates
  your webhook secret and sponsorship config — and must not be reachable from a browser.
</Warning>

## CORS and the version header

All three modals send `x-deposit-modal-version` on every request. Browsers reject a request carrying a header the server didn't allow on the preflight, so an explicit allow-list must include it:

```ts theme={null}
allowHeaders: ["Content-Type", "x-deposit-modal-version"]
```

Bare `cors()` in Hono is fine — with no `allowHeaders` it reflects whatever the preflight asks for.

<Warning>
  This bites on upgrade, not on first deploy. A modal version that starts sending a new
  header fails the **whole request** at preflight against a proxy with a fixed
  allow-list, not just the header. Deploy proxy changes before the modal that needs them.
</Warning>

Forwarding it upstream is optional, but it lets a support request be matched to the exact build you're running. To read the value in your own app, for a bug report:

```ts theme={null}
import { MODAL_VERSION } from "@rhinestone/deposit-modal/constants";
```

## Regional payment methods

Fiat on-ramp methods vary by country, and your proxy is the only component that can see the end user: the processor sits behind it and only ever observes your proxy's address. So `GET /onramp/swapped/payment-methods` returns the generic method set unless your proxy names the user's region.

You do **not** need a GeoIP database — the processor owns the lookup. The proxy only names what it observed, which takes one of two variables:

* `TRUSTED_COUNTRY_HEADER` — you're behind a CDN that already resolves country, so forward its header (`cf-ipcountry`, `x-vercel-ip-country`, `cloudfront-viewer-country`).
* `TRUSTED_PROXY_HOPS` — nothing resolves it for you, so relay the client IP and let the processor resolve it.

Either one also requires `TRUSTED_PROXY_CIDRS`, an allowlist of the peers permitted to set forwarding headers. Without it any browser could send `x-forwarded-for` or `cf-ipcountry` and choose its own region, so [Rhinestone's proxy](#deploy-the-rhinestone-proxy) refuses to start when you set one without the other. See its [README](https://github.com/rhinestonewtf/deposit-widget-proxy#regional-payment-methods) for the details, including why hops are counted from the right.

<Note>
  Every path here fails closed. A wrong setting costs you localization, not correctness: you get the generic method set rather than a region that isn't the user's. A hand-written proxy that relays nothing behaves exactly as it does today.
</Note>

## Webhooks

The widget's [lifecycle callbacks](/deposits/widget/status-tracking) fire only while the modal is open, so a user who closes it mid-bridge leaves your app unaware the deposit completed. Anything that must happen regardless — crediting a balance, sending a receipt — belongs on a [webhook](/deposits/api/status-tracking) handler. Configure it once with `POST /setup`.