Using the API

How the Rhinestone Orchestrator API works and what to keep in mind when integrating.

The Rhinestone Orchestrator API follows a quote-sign-submit flow. Each step is covered in the API guides section, but there are a few rules that apply across the entire integration.

Pin a version

Send x-api-version: 2026-04.blanc on every request:

const headers = {
  "Content-Type": "application/json",
  "x-api-key": apiKey,
  "x-api-version": "2026-04.blanc",
};

Requests without the header fall back to the deprecated 2026-01.alps shape. See API versioning for the full versioning policy.

Server-stored intents

Quote responses are stored server-side. POST /quotes returns an intentId and the typed data needed for signing — you don’t round-trip the full intent through the client. Submit by id:

const { routes } = await post("/quotes", body);
const { intentId, signData } = routes[0];

const signatures = {
  origin: await Promise.all(signData.origin.map(signTypedData)),
  destination: await signTypedData(signData.destination),
};

await post("/intents", { intentId, signatures });

Pick routes[0] unless you have your own ranking — the array is server-ranked by a cost/speed tradeoff.

Quote expiry

Quotes have a short server-side TTL. If a quote expires (or the quote store restarts) before you submit, POST /intents returns a 404. Re-quote and re-sign — don’t retry the submit.

One signature per origin chain

signData.origin is one entry per source chain. Sign each one in order. If the recipient differs from the sender and the destination has executions, sign signData.destination too — this slot is used for ownership of any received tokens.

Forward typed data verbatim

Don’t reconstruct EIP-712 types client-side. Forward the server’s typed data directly to wallet.signTypedData(). Hand-rolled type libraries break on additive schema changes.

API key scopes

Each API key can be scoped to bound its blast radius. Three scopes apply: allowMainnet, intents, and deposits. All default to unrestricted: the keys are “allow all” by default. Edit scopes from the Dashboard on the key detail screen (OWNER or ADMIN only). Denials return HTTP 403 with the failed scope and the required/actual levels in the error body.

Scope	Values	What it allows
allowMainnet	true / false	When false, restricts the key to testnet chains.
intents	none / read / write	Gates the intent flow. none blocks it; read permits non-mutating calls (quoting, status); write adds intent submission.
deposits	none / read / write	Gates the deposit lifecycle. none blocks it; read permits non-mutating calls; write adds account setup and state mutations.

Account introspection endpoints (portfolio, liquidity) are not gated by intents or deposits — they stay accessible at any level, which is useful for monitoring keys.

Scopes only gate the customer API. On-chain deposits into already-registered accounts continue to flow through inbound provider webhooks regardless of scope. Set intents: 'none' (or revoke the key) to block intent submission for existing users.

Next steps

Setting up approvals

Handle token approvals and ETH wrapping before signing.

Signing the intent

Sign each element of the intent with EIP-712.