> For the complete documentation index, see [llms.txt](https://docs.useicaria.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.useicaria.xyz/architecture/api.md).

# API and SDK

The public quote API, the TypeScript SDK, and the protocol that makers speak.

Without an API, Icaria would only ever be a website. With one, it is a backend: wallets, portfolio tools, aggregators and agents draw on the same pricing the platform does and settle through the same public router. No partner tier exists and no endpoint is privileged. Everything documented here is exactly what the reference front-end runs on.

## Quote API (REST)

```
GET /v1/quote?tokenIn=USDG&tokenOut=AAPL&amountIn=2000000000
```

```json
{
  "amountOut": "9873400000000000000",
  "breakdown": {
    "mid": "202.41",
    "spreadBps": 10,
    "skewBps": -2,
    "feeBps": 2,
    "regime": "OPEN",
    "oracleRound": "0x…"
  },
  "venue": "vault",
  "rfq": { "quote": { "…": "…" }, "signature": "0x…" },
  "validUntil": 1788316201,
  "tx": { "to": "0xSwapRouter…", "data": "0x…" }
}
```

Responses itemise the breakdown, state which venue priced best, carry any winning RFQ quote together with the signature the chain will verify, and include calldata ready to sign with the trader's bound already applied. Treat a quote as a preview: since the chain re-derives or re-verifies all of it, a bad quote can send an integrator into a revert but never into a bad fill.

The rest of the surface is `/v1/markets` for listings, tiers, parameters and regimes, `/v1/fills` for paginated fill history with breakdowns, `/v1/execution-quality` for the dataset behind the [transparency page](/transparency/execution-quality.md), and `/v1/eligibility/:address` to preview a role check.

## WebSocket

Regime changes, per-market quote updates at feed cadence and fill events all arrive on `wss://api.useicaria.xyz/v1/stream`. That same stream is what feeds the platform's tickets.

## TypeScript SDK

```ts
import { Icaria } from "@icaria/sdk";

const z = new Icaria({ chainId: 4663, signer });
const quote = await z.quote({ tokenIn: "USDG", tokenOut: "AAPL", amountIn: 2_000_000000n });
console.log(quote.breakdown);          // mid, spread, skew, fee, regime
const receipt = await z.swap(quote, { maxSlippageBps: 15 });
```

Quoting, Permit2 signing, eligibility preflight and receipt decoding are handled inside the SDK, which also ships typed events for anyone consuming the indexer. Versions follow semver with a published changelog, and breaking changes never arrive unannounced.

## Maker protocol

An authenticated WebSocket is how makers connect. Requests get broadcast to them, and EIP-712 signatures come back:

```
→ { "type": "rfq", "id": "…", "tokenIn": "USDG", "tokenOut": "NVDA", "amountIn": "250000000000" }
← { "type": "quote", "id": "…", "quote": { …EIP-712 fields… }, "signature": "0x…" }
```

Admission needs a `MAKER` attestation, and the message schema, the signing domain and the advice on nonce management are in the maker guide at [For market makers](/using-icaria/market-makers.md). Losing an auction costs nothing, quoting obligations do not exist at launch, and makers who quote consistently move up the routing priority.

## Keys and rate limiting

Quote endpoints are open with per-IP rate limits, and an authenticated key lifts those limits and opens the WebSocket. Identifying integrators for support and abuse control is the entire purpose of a key. Pricing is untouched by them, which anyone can confirm, since vault pricing is a public contract read.

## Versioning

`/v1` is stable. Deprecations get announced in the changelog at least 90 days ahead, and the SDK pins its API version explicitly. Contract addresses per deployment are on the [Deployment](/architecture/deployment.md) page.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.useicaria.xyz/architecture/api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.