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

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

```ts theme={null}
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](./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:

```ts theme={null}
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](https://dashboard.rhinestone.dev) 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.

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

## Next steps

<CardGroup cols={2}>
  <Card title="Setting up approvals" icon="list-check" href="./token-requirements">
    Handle token approvals and ETH wrapping before signing.
  </Card>

  <Card title="Signing the intent" icon="signature" href="./signing">
    Sign each element of the intent with EIP-712.
  </Card>
</CardGroup>