> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravn.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# @ravn/sdk

> Typed client for /api/v1, quote, execute, submit-signature, and status.

A thin, zero-dependency wrapper around the four calls in the [Quickstart](/quickstart). Same
request and response shapes as the raw API, just typed, with one error type instead of parsing
HTTP status codes yourself.

## Setup

```ts theme={null}
import { RavnClient } from "@ravn/sdk";

const client = new RavnClient({
  apiKey: "rvn_live_your_key_here", // optional, omit for the anonymous tier
});
```

<ParamField body="apiKey" type="string">Self-serve or enterprise key. Omit for the anonymous tier: it works immediately, at a lower rate limit. See [Authentication](/authentication).</ParamField>
<ParamField body="baseUrl" type="string">Default `https://ravn.exchange/api/v1`.</ParamField>
<ParamField body="fetch" type="function">Swap in your own `fetch` (React Native, a test double). Defaults to the global `fetch`.</ParamField>

## Full example

Quote, execute, and track a swap end to end. `execution.executionType` also branches to
`TRANSACTION` or `SIGNATURE`; see the [Quickstart](/quickstart) for the full switch.

```ts theme={null}
const quote = await client.getQuote({
  inputChainId: 1,
  outputChainId: -2,
  inputToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  outputToken: "So11111111111111111111111111111111111111112",
  inputAmount: "1000000000000000000",
  userAddress: "0xYourUser",
  destinationAddress: "SoYourUser",
});

const execution = await client.execute({ quoteToken: quote.quoteToken });

if (execution.executionType === "DEPOSIT") {
  await wallet.send(execution.deposit.address, execution.deposit.amount);
  const status = await client.getStatus(quote.quoteToken, execution.statusRef);
}
```

## Methods

Every method throws `RavnApiError` on a non-2xx response; see [Errors](#errors) below. Field
meanings match the [API Reference](/api-reference/overview) pages linked from each method.

### getQuote

```ts theme={null}
const quote = await client.getQuote({
  inputChainId: 1,
  outputChainId: -2,
  inputToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  outputToken: "So11111111111111111111111111111111111111112",
  inputAmount: "1000000000000000000",
  userAddress: "0xYourUser",
  destinationAddress: "SoYourUser",
});
```

Wraps [`POST /quote`](/api-reference/quote). Omitting `destinationAddress`/`refundAddress`
returns a preview-only quote, so check `quote.executable` before calling `execute`.

### execute

```ts theme={null}
const execution = await client.execute({ quoteToken: quote.quoteToken });

switch (execution.executionType) {
  case "TRANSACTION": /* ... */ break;
  case "SIGNATURE": /* ... */ break;
  case "DEPOSIT": /* ... */ break;
}
```

Wraps [`POST /execute`](/api-reference/execute). Branch on `executionType` exactly as in the
[Quickstart](/quickstart). This client doesn't sign or send anything for you.

### submitSignature

```ts theme={null}
const { statusRef } = await client.submitSignature({
  quoteToken: quote.quoteToken,
  signature: sig,
});
```

Wraps [`POST /submit-signature`](/api-reference/submit-signature). Only for `SIGNATURE`-type
executions. Returns the `statusRef` to poll `getStatus` with.

### getStatus

```ts theme={null}
const status = await client.getStatus(quote.quoteToken, statusRef);
```

Wraps [`GET /status`](/api-reference/status). `ref` is the `statusRef` from `execute` (for
`DEPOSIT`) or from `submitSignature` (for `SIGNATURE`), matching the Full example above.

## Errors

Every non-2xx response throws a `RavnApiError`, never a raw fetch or JSON error:

```ts theme={null}
import { RavnApiError } from "@ravn/sdk";

try {
  await client.execute({ quoteToken });
} catch (err) {
  if (err instanceof RavnApiError) {
    console.log(err.code, err.message, err.details);
  }
}
```

<ResponseField name="code" type="string">The stable, machine-readable code. See [Errors](/errors) for the full table.</ResponseField>
<ResponseField name="message" type="string">Human-readable, and can change. Don't branch on it.</ResponseField>
<ResponseField name="details" type="unknown">Present on some codes, for example the failed fields on `INVALID_REQUEST`.</ResponseField>
<ResponseField name="meta" type="object">`requestId` and `version`, when the API returned an envelope at all.</ResponseField>