@ravn/react

Three hooks, one per @ravn/sdk call that benefits from React state: quote fetching with expiry tracking, execute as an async action, and status as a poll. You still bring your own wallet; these hooks never sign or send anything.

peer dependency

Requires React 18 or later.

peer dependency

Create one RavnClient and pass it to every hook.

import { RavnClient } from "@ravn/sdk";
import { useRavnQuote, useRavnExecute, useRavnStatus } from "@ravn/react";

const client = new RavnClient(); // create once, pass to every hook below

useRavnQuote

const { quote, isLoading, error, isExpired, refetch } = useRavnQuote(client, {
  inputChainId: 1,
  outputChainId: -2,
  inputToken: "0xEeee...EEeE",
  outputToken: "So1111...1112",
  inputAmount: amount, // e.g. from a controlled input
  userAddress: address,
});

Fetches whenever params changes (compared by value, not by reference, so a fresh object literal on every render is fine), and sets isExpired on its own timer when quote.expiresAt passes: no polling, one setTimeout per quote. Pass params: null to skip fetching, for example when the amount hasn’t been entered yet.

Does not auto-refetch on expiry. Silently re-pricing behind the user’s back is worse than telling them to ask again, so call refetch() yourself in response to isExpired.

QuoteDTO | null

boolean

unknown

A RavnApiError on a failed request. See Errors.

boolean

True once quote.expiresAt has passed. Stop letting the user sign, and call refetch().

() => void

useRavnExecute

const { execute, data, isLoading, error } = useRavnExecute(client);

const handleSwap = async () => {
  const execution = await execute({ quoteToken: quote.quoteToken });
  switch (execution.executionType) {
    case "TRANSACTION": /* ... */ break;
    case "SIGNATURE": /* ... */ break;
    case "DEPOSIT": /* ... */ break;
  }
};

A thin state wrapper around client.execute(). Branch on the returned executionType and hand it to whatever signer you already have: wagmi, ethers, a hardware wallet. Same contract as the Quickstart.

(params: ExecuteParams) => Promise<ExecutionDTO>

Also throws on failure. Handle the rejection or read error, whichever fits your flow.

ExecutionDTO | null

boolean

unknown

useRavnStatus

const { status, isLoading, error } = useRavnStatus(
  client,
  execution ? { quoteToken: quote.quoteToken, ref: statusRef } : null,
  4_000 // poll interval in ms, optional, default 4000
);

Polls GET /status until the status leaves pending/processing: expired, success, refunded, failed, not_found, and unknown all stop the poll. Pass params: null to not poll at all, for example before execution has produced a ref.

expired stops this hook, but it isn’t a final outcome. Per Status, a refund can still land later and flip it to refunded. This hook has no refetch, so to catch that later transition, call client.getStatus() yourself after a delay, or remount the hook.

Keeps polling through a transient network or 5xx error. Stops immediately on a permanent one, UNAUTHORIZED, INVALID_REQUEST, QUOTE_INVALID, or NOT_FOUND, since retrying with the same arguments can never turn one of those into success.

StatusDTO | null

boolean

unknown

Putting it together

function SwapButton({ params }: { params: GetQuoteParams }) {
  const { quote, isExpired, refetch } = useRavnQuote(client, params);
  const { execute, data: execution } = useRavnExecute(client);
  const { status } = useRavnStatus(
    client,
    execution?.executionType === "DEPOSIT"
      ? { quoteToken: quote!.quoteToken, ref: execution.statusRef }
      : null
  );

  if (isExpired) return <button onClick={refetch}>Refresh quote</button>;
  return (
    <button onClick={() => execute({ quoteToken: quote!.quoteToken })}>
      {status ? `Status: ${status.status}` : "Swap"}
    </button>
  );
}

Overview

Guides

API Reference

SDKs & Widget

AI Agents

@ravn/react

useRavnQuote

useRavnExecute

useRavnStatus

Putting it together

​useRavnQuote

​useRavnExecute

​useRavnStatus

​Putting it together

useRavnQuote

useRavnExecute

useRavnStatus

Putting it together