# Quickstart

No signup, no key, no wallet needed to read. These calls work right now:

```sh
curl https://ultra-api.deserialize.xyz/v1/health
curl https://ultra-api.deserialize.xyz/v1/chains

# a real meta-aggregated quote: 1 SOL -> USDC
curl -X POST https://ultra-api.deserialize.xyz/v1/swaps/quote \
  -H "content-type: application/json" \
  -d '{"chain":"solana",
       "inputToken":"So11111111111111111111111111111111111111112",
       "outputToken":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
       "amountIn":"1000000000"}'
```

## The four-step integration path

1. **Read** — call any GET endpoint. Nothing is required but the URL.
2. **Quote** — POST a `/quote` endpoint to price an action. Quotes are never cached and expire.
3. **Build** — POST a `/build` endpoint with the user's address as `taker`/`owner`. You get `steps[]`. Swap-shaped builds accept `"simulate": false` to skip the pre-return simulation gate (see Safety guarantees).
4. **Execute** — walk `steps[]` in order with the user's wallet. The API is not involved.

## Authentication and rate limits

- **Auth is optional.** No key is required for any endpoint. Free tier: **10 requests/second per IP**.
- **Enterprise keys are not rate limited.** Send yours as the `x-api-key` header. Keys are issued manually: email sales@deserialize.xyz → invoice → on payment the key is issued.
- Over the limit returns HTTP 429 `PROVIDER_RATE_LIMITED` with `retry-after` and `x-ratelimit-*` headers.
- `partnerFeeBps` / `partnerFeeRecipient` take an integrator fee where the venue supports one natively. **The fee is applied at quote time**, so send it to `/quote` as well as `/build` — a quote without it will not match the build. Where it works: **KyberSwap** (EVM, incl. `/v1/rwa`) charges it on the output token; **Jupiter** (Solana) charges it on the quote, and `partnerFeeRecipient` must be a Jupiter *referral token account for the output mint*, not a wallet. Where it does not: **LiFi** needs a registered integrator (portal.li.fi) and refuses otherwise; **Hyperliquid**, **four.meme** and **Polymarket** have no integrator-fee field at all. In every unsupported case the build returns a `partnerFee NOT applied` warning rather than silently pretending — check `warnings[]`. Fees are capped at 1000 bps (10%). When a venue does charge, the quote carries `fee: {amount, token, bps, recipient, chargedOn}` — the amount the **venue itself reported**, in base units of `token`, not the bps you asked for. `GET /v1/fees/summary?recipient=…` totals those per chain and token. **Read its `note` before treating any of it as revenue: these are fees accrued on actions we returned, not fees earned** — this API never learns whether you signed or broadcast, so reconcile against the recipient address on-chain. An unscoped summary (no `recipient`) requires an enterprise key, since auth is otherwise open.

## Optional TypeScript SDK

The REST API is complete on its own; the SDK just wraps it and executes steps.

```ts
npm i @deserialize/ultra-agg-sdk

import { UltraAggClient, executeSteps } from '@deserialize/ultra-agg-sdk'
const ultra = new UltraAggClient({ baseUrl: 'https://ultra-api.deserialize.xyz' })
const action = await ultra.swapBuild({ chain, inputToken, outputToken, amountIn, taker })
await executeSteps(action, wallet)   // wallet signs; the SDK never sees a key
```