Client

The client is a typed wrapper over the HTTP API. Each method is one request, except waitForDelivery, which polls. Every response is checked against the SDK's schema before you get it.

import { createXebraClient } from "@xebra/sdk";

const xebra = createXebraClient();

OptionsCopy Anchor Link

const xebra = createXebraClient({
  baseUrl: "https://api.xebra.exchange",
  timeoutMs: 15_000,
});

MethodsCopy Anchor Link

routes()Copy Anchor Link

Every route Xebra sends on right now, read from the contracts and the live configuration. If part of the list could not be read, complete is false and the list may be short; ask again shortly.

const { routes, complete } = await xebra.routes();
const fromStellar = routes.filter((r) => r.from === "stellar").map((r) => r.to);

quote(q)Copy Anchor Link

What a transfer costs and what the recipient gets. Read-only.

const quote = await xebra.quote({
  from: "arc",
  to: "solana",
  amount: "100",
  speed: "fast", // optional; "standard" when left out
  recipient: "7xKX...", // pass it for Solana: opening a USDC account costs more
});

For Solana, pass recipient. A wallet with no USDC account yet costs more to deliver to, and the quote includes that only if it knows the recipient.

createTransfer(r)Copy Anchor Link

The unsigned transactions for a transfer, in signing order, and the quote they were built at.

const { quote, steps } = await xebra.createTransfer({
  from: "base",
  to: "arc",
  amount: "50",
  sender: "0xSender...",
  recipient: "0xRecipient...",
  maxTotalFee: "0.10",
});

sender is the address that signs and pays. recipient is who receives on the destination. Set maxTotalFee to the total you showed the user: if fees have risen above it, the request fails with fee_above_limit instead of building a more expensive transfer.

The API checks what it can before it builds: the recipient's format, the sender's USDC balance, and on Stellar a simulation of the contract call. A transfer that would fail is refused with a code, before anyone is asked to sign.

Each step:

Ask the wallet for each step in order, and wait for each to confirm before the next. An approve must be included on chain before the burn that spends it.

let burnHash: string | undefined;
for (const step of steps) {
  const hash = await signAndSend(step); // your wallet code; wait for confirmation
  if (step.id === "burn") burnHash = hash;
}

getTransfer(chain, tx)Copy Anchor Link

Where a transfer is, by the chain it started on and the burn's transaction hash (or Sui digest). For Stellar the hash is 64 hex characters without 0x; for an EVM chain it is 0x and 64 hex characters.

const status = await xebra.getTransfer("base", burnHash);

waitForDelivery(chain, tx, opts?)Copy Anchor Link

Polls getTransfer until the state is delivered, needs_claim or failed, and returns that status. A moment where Circle or the API cannot be reached (upstream_unavailable, rate_limited, network_error, timeout) is waited out, not thrown. Any other error is thrown at once.

const controller = new AbortController();

const status = await xebra.waitForDelivery("stellar", burnHash, {
  intervalMs: 5_000, // default 5 s
  timeoutMs: 30 * 60_000, // default 30 min
  signal: controller.signal, // stop early, for example when the user leaves the page
});

If the deadline passes first, it throws XebraApiError with code timeout. That does not mean the transfer failed: it may still settle. Ask again later.

Aborting the signal rejects with the signal's reason, not with an XebraApiError.

createClaim(r)Copy Anchor Link

The unsigned mint for a transfer whose delivery did not complete on its own (state needs_claim or failed). payer signs and pays the destination's network fee. See Claim a stuck transfer.

const { steps } = await xebra.createClaim({
  chain: "stellar", // the chain the burn was made on
  tx: burnHash,
  payer: "0xPayer...", // on the destination chain
});

For a claim on Solana where the recipient's USDC account must be opened, also pass recipientOwner, the wallet that owns it. The answer then may start with an open_account step.

health()Copy Anchor Link

{ status: "ok", version } when the API is up. version is the API's SDK version.

ErrorsCopy Anchor Link

Every failure is thrown as XebraApiError. Its code is stable and safe to branch on; its detail is a sentence written for a person.

try {
  await xebra.quote({ from: "stellar", to: "base", amount: "500" });
} catch (err) {
  if (err instanceof XebraApiError && err.code === "amount_above_maximum") {
    console.log(`At most ${err.extra.maximum} USDC per transfer.`);
  } else if (err instanceof XebraApiError) {
    console.log(err.status, err.code, err.detail);
  } else {
    throw err;
  }
}

Three codes come from the client itself, not the API:

• network_error: the request did not reach the API.
• timeout: no answer within timeoutMs, or waitForDelivery ran out of time.
• invalid_response: the API answered with something that is not JSON or does not match the SDK's schema.

The list of every code, with its HTTP status, is exported as ERROR_STATUS and ERROR_CODES.

CancellingCopy Anchor Link

getTransfer and waitForDelivery take an AbortSignal. The client's own timeout still applies to each request.