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

# TypeScript SDK

> Quote a route, verify it, and build a swap transaction with @xoxno/sdk-js.

`@xoxno/sdk-js` wraps the quote endpoint and builds the router call. It does not sign or submit. Server-prepared envelopes (`transaction.simulated: true`) already include the live source account sequence. When building a transaction locally with the SDK, supply `sourceSequence` yourself. Wallet signing and submission remain with the integrator.

```bash theme={"system"}
npm install @xoxno/sdk-js @stellar/stellar-sdk
```

## Functions

| Function | Use |
| - | - |
| `getStellarAggregatorQuote(request, { baseUrl })` | Calls `GET /api/v1/quote`. Requires exactly one of `amountIn` or `amountOut`. |
| `getStellarQuoteTokens({ baseUrl })` | Calls `GET /api/v1/tokens`. |
| `mapQuoteResponseToStrategySwap(quote, { network, expected })` | Decodes `routeXdr` and checks it against your request. Throws `StellarRouteVerificationError` on a mismatch. |
| `buildStellarExecuteStrategyTx(options, swap)` | Builds an unsigned `execute_strategy(sender, total_in, swap_xdr)` transaction and returns `{ xdr }`. |
| `prepareStellarTxXdr(server, xdr)` | Simulates through Stellar RPC and attaches resources. |

The SDK has no default endpoint. Pass `baseUrl` explicitly (`https://stellar-swap.xoxno.com` for the public service).

## Swap from a wallet

```ts theme={"system"}
import {
  buildStellarExecuteStrategyTx,
  getStellarAggregatorQuote,
  mapQuoteResponseToStrategySwap,
  prepareStellarTxXdr,
} from "@xoxno/sdk-js";
import { rpc } from "@stellar/stellar-sdk";

const baseUrl = "https://stellar-swap.xoxno.com";
const config = await (await fetch(`${baseUrl}/api/v1/config`)).json();

const quote = await getStellarAggregatorQuote(
  { from: tokenIn, to: tokenOut, amountIn, slippage: 0.01 },
  { baseUrl },
);

// Throws if the route does not spend tokenIn, deliver tokenOut, or enforce
// a minimum at least as high as quote.amountOutMin. Never sign after a throw.
const swap = mapQuoteResponseToStrategySwap(quote, {
  network: config.network,
  expected: { tokenIn, tokenOut, minOut: quote.amountOutMin ?? undefined },
});

const server = new rpc.Server(rpcUrl);
const account = await server.getAccount(walletAddress);

const { xdr } = buildStellarExecuteStrategyTx(
  {
    network: config.network,
    caller: walletAddress,
    sourceSequence: account.sequenceNumber(),
    routerAddress: config.router,
    totalIn: quote.amountIn,
  },
  swap,
);

const preparedXdr = await prepareStellarTxXdr(server, xdr);
// Review the prepared transaction, sign with the wallet, submit, and confirm.
```

Pass `quote.amountIn` as `totalIn`. It is the gross input, including any input-side fee. The SDK builds this transaction itself, so you do not need to use the `transaction.envelopeXdr` the server can return when you pass `sender`. Use that envelope, or this builder, but not both.

## Compose with lending

Pass `swap` (or `quote.routeXdr`) as the strategy `steps` argument of the lending builders. Keep the payload opaque, and simulate the complete outer transaction. See [Execution models](/docs/stellar-aggregator/execution-planes).

## Known differences from the API

Use `@xoxno/sdk-js` 1.0.222 or later. Earlier versions typed token entries with fields the service never returned and sent an ignored `router` parameter.

* **Token IDs.** Use canonical `C…` contract IDs. The service rejects `XLM` and `CODE:ISSUER` forms with `invalid_request`.
* **`router`.** The service ignores a `router` request field and uses the router from `/api/v1/config`. The SDK no longer sends it.
* **`alternatives`.** The `@xoxno/types` response type still declares it, but the service no longer returns it.
* **`transactions[]`.** The SDK builds a single-swap transaction. For an LP conversion that returns `transactions[]`, follow the [ordered plan procedure](/docs/stellar-aggregator/execution-planes).
* **`simulate`.** Pass `simulate: false` to skip server-side simulation when you send a `sender`.

[Quickstart](/docs/stellar-aggregator/quickstart) · [Error recovery](/docs/stellar-aggregator/error-reference)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.