@ravnexchange/sdk

npm install @ravnexchange/sdk

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

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

string

Your public key. Never put the secret key in browser code.

object | false

Tunes the check before the wallet: { solanaRpcUrl } to simulate Solana transactions on your RPC, { allowContracts: { [chainId]: ["0x…"] } } to accept a venue’s new contract early. false turns it off.

string

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

function

Your own fetch (React Native, tests).

These docs cover the latest version. What changed between versions is in the changelog.

executeAndTrack

Runs a whole swap from a quoteToken: execute, approvals, the swap, your fee, then status polling to a final state. It works for every execution type and chain, given your own wallet functions.

import { executeAndTrack } from "@ravnexchange/sdk";

const quote = await client.getQuote({ /* … */ });

const result = await executeAndTrack(
  client,
  { quoteToken: quote.quoteToken },
  {
    sendTransaction: ({ to, data, value, gasLimit }) =>
      wallet.sendTransaction({
        to: to!.toLowerCase() as `0x${string}`, // lowercase passes viem's checksum check
        data: data as `0x${string}`,
        value: BigInt(value ?? "0"),
        gas: gasLimit ? BigInt(gasLimit) : undefined,
      }),
    waitForReceipt: (hash) => wallet.waitForTransactionReceipt({ hash: hash as `0x${string}` }),
    signTypedData: (typedData) => wallet.signTypedData(typedData as any),
  },
  {
    sendDeposit: true,
    onProgress: ({ partial }) => db.saveSwap(partial), // every hash, the moment it exists
  }
);

result.finalStatus?.status; // "success", "refunded", "failed" or "unknown"

Handlers. Give it only what your app can do:

Handler	Needed for
`sendTransaction(tx)`	Every EVM transaction. Return the hash. Send `tx.gasLimit` as the gas limit when set
`waitForReceipt(hash)`	Every EVM transaction. Return the receipt itself: RAVN’s fee is sent only after a successful swap receipt
`signTypedData(typedData)`	`SIGNATURE` executions, and Hinkal’s order step
`sendCalls(txs)`	Optional. Sends calls in one EIP-5792 batch when `batch` allows. Return each call’s on-chain transaction hash
`signSolanaTransaction(serialized)`	Solana transactions that carry `submit` (`broadcastViaRavn` quotes). Sign, don’t send
`sendBitcoinPsbt(psbt)`	Bitcoin deposits, with `sendDeposit`. Sign, finalize, broadcast, return the txid
`sendSolanaTransaction(serialized)`	Solana deposits, with `sendDeposit`. Sign, send, return the signature
`signMessage(message)`, `switchChain(chainId)`	Hinkal’s `AUTHORIZE` steps
`hasAllowance(approval)`	Optional. Your own allowance read, to skip an approval you don’t need

Every handler that sends should reject only when nothing was sent. Options

Option	Default
`sendDeposit`	`false`	Also send `DEPOSIT`s and their fee, from the ready-made payload. Without it you send deposits yourself (`result.feePayment` says what to pay beside one)
`onProgress`		Called with every hash as it exists, and on every poll. Persist `partial` to resume after a crash
`pollUntilTerminal`	`true`	`false` returns once everything is sent; then poll `getStatus` yourself
`pollIntervalMs`	`4000`	Use 10,000 to 15,000 for Bitcoin deposits
`maxWaitMs`	none	Stop polling after this long. Set it on a backend
`signal`		An `AbortSignal` to stop

Result: execution, quoteToken (the one /execute returned), txHash, statusRef, statusTxHash, approvalTxHash, feeTxHash, feeError (why your fee wasn’t sent or proven, if it wasn’t), finalStatus, and with sendDeposit on, depositNotSent (why a deposit wasn’t sent: send it yourself).

With sendDeposit on, send a deposit yourself only when depositNotSent is set, or your user pays twice. On a sandbox execution nothing is sent.

Errors and resuming. Before anything is sent, it rejects with the underlying error. After that, it rejects only with an ExecuteAndTrackError (code: FAILED, ABORTED or TIMEOUT) whose partial holds every hash so far. Keep polling with getStatus(partial.quoteToken, partial.statusRef, partial.statusTxHash).

Methods

Each wraps one endpoint with the same fields as the API reference and throws RavnApiError on failure.

Method	Endpoint
`getQuote(params)`	`POST /quote`
`getQuoteStream(params, { onEvent })`	`POST /quote` with `stream: true`. `onEvent` gets each venue’s prices; it resolves to the same quote as `getQuote`
`execute({ quoteToken, idempotencyKey? }, { intent? })`	`POST /execute`. Checked before it returns (see below)
`submitSignature({ quoteToken, signature, approvalSignature? })`	`POST /submit-signature`
`submitTransaction({ quoteToken, signedTransaction })`	`POST /submit-transaction`
`getStatus(quoteToken, ref, txHash?, { signal? })`	`POST /status`. Doesn’t retry: retry `RATE_LIMITED`, `5xx` and `NETWORK_ERROR` yourself
`getTokens(chainId)`, `getChains()`	`GET /tokens`, `GET /chains`
`recover(params, { userAddress })`	One step of `POST /recover`, checked

depositFeePayment

depositFeePayment(execution) says what fee to pay beside a DEPOSIT you send yourself: kind transaction (EVM: send it once the deposit confirms), bitcoin_output or solana_transfer (add it to the deposit’s own transaction). undefined when there’s none.

recoverStuckFunds

Gets a failed Hinkal swap’s funds back to the paying wallet, checking every step before it’s signed:

import { recoverStuckFunds } from "@ravnexchange/sdk";

const { recovered } = await recoverStuckFunds(
  client,
  { statusRef, userAddress }, // userAddress: the paying wallet, from your own wallet connection
  {
    signMessage: (message) => wallet.signMessage({ message }),
    signTypedData: (typedData) => wallet.signTypedData(typedData),
    switchChain: (chainId) => wallet.switchChain({ id: chainId }), // optional
  }
);

The check before the wallet

execute (and so executeAndTrack) checks every execution against what your user asked to swap before you can hand it to a wallet. It throws UnsafeExecutionError unless:

EVM transactions and approvals go only to contracts RAVN’s venues use, and touch only the input token, up to the input amount;
no more native coin is sent than the input amount, and none on a token sell;
RAVN’s fee goes only to RAVN and is at most 1%;
signatures are of kinds RAVN’s venues use, for the input token, up to the amount;
a Bitcoin PSBT pays only the deposit, RAVN’s fee and change back to the sender;
a Solana transaction calls only programs RAVN’s venues use and moves at most the input amount. With guard: { solanaRpcUrl } it’s also simulated on your RPC (Agave 2.3 or later), and every transfer out of the user’s accounts must stay within the swap.

It knows what was asked from your own getQuote. For a quoteToken quoted elsewhere (say, on your server), pass it: execute({ quoteToken }, { intent: { inputChainId, inputToken, inputAmount, userAddress } }). Quote with token addresses, not symbols. What it can’t see: whether a venue pays out fairly once funds are in its contract, and allowances the user already gave those contracts. Without a Solana RPC, rely on the wallet’s own simulation. An UnsafeExecutionError means nothing was sent: get a fresh quote, and tell RAVN if it persists.

Errors

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

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

code is the API error code, or NETWORK_ERROR when no response came back.

​executeAndTrack

​Methods

​depositFeePayment

​recoverStuckFunds

​The check before the wallet

​Errors

executeAndTrack

Methods

depositFeePayment

recoverStuckFunds

The check before the wallet

Errors