Skip to main content
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:
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.

Deploy the Rhinestone proxy

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, and adds 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:
Point backendUrl at it and check GET /health. Everything else is optional and documented in the repository’s README:

Minimal proxy

A proxy is an explicit route table plus a header. The allowlist is the security boundary — see the warning below.
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.

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

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:
Bare cors() in Hono is fine — with no allowHeaders it reflects whatever the preflight asks for.
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.
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:

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 refuses to start when you set one without the other. See its README for the details, including why hops are counted from the right.
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.

Webhooks

The widget’s lifecycle callbacks 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 handler. Configure it once with POST /setup.