@ravn/sdk

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

Setup

import { RavnClient } from "@ravn/sdk";

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

string

Self-serve or enterprise key. Omit for the anonymous tier: it works immediately, at a lower rate limit. See Authentication.

string

Default https://ravn.exchange/api/v1.

function

Swap in your own fetch (React Native, a test double). Defaults to the global fetch.

Full example

Quote, execute, and track a swap end to end. execution.executionType also branches to TRANSACTION or SIGNATURE; see the Quickstart for the full switch.

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 below. Field meanings match the API Reference pages linked from each method.

getQuote

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

Wraps POST /quote. Omitting destinationAddress/refundAddress returns a preview-only quote, so check quote.executable before calling execute.

execute

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

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

Wraps POST /execute. Branch on executionType exactly as in the Quickstart. This client doesn’t sign or send anything for you.

submitSignature

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

Wraps POST /submit-signature. Only for SIGNATURE-type executions. Returns the statusRef to poll getStatus with.

getStatus

const status = await client.getStatus(quote.quoteToken, statusRef);

Wraps GET /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:

import { RavnApiError } from "@ravn/sdk";

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

string

The stable, machine-readable code. See Errors for the full table.

string

Human-readable, and can change. Don’t branch on it.

unknown

Present on some codes, for example the failed fields on INVALID_REQUEST.

object

requestId and version, when the API returned an envelope at all.

Overview

Guides

API Reference

SDKs & Widget

AI Agents

Setup

Full example

Methods

getQuote

execute

submitSignature

getStatus

Errors

​Setup

​Full example

​Methods

​getQuote

​execute

​submitSignature

​getStatus

​Errors

Setup

Full example

Methods

getQuote

execute

submitSignature

getStatus

Errors