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

# Built-in UI (Beta)

> Open AIR Kit's hosted UI for token swap, send and receive flows, transaction history, and wallet management directly inside your dApp (beta).

## Swap Interface

### showSwapUI()

Opens the AIR Kit swap interface, allowing users to exchange tokens directly within your application.

**Method Signature:**

```ts theme={null}
public async showSwapUI(options?: {
  initialFromToken?: TokenSymbol;
  fallbackFromToken?: TokenSymbol;
  initialToToken?: TokenSymbol;
  defaultSlippage?: number;
}): Promise<{
  txHash: `0x${string}`;
  from: Token & { amount: string };
  to: Token & { amount: string };
}>
```

Each token is identified by symbol and chain, not by a bare string:

```ts theme={null}
type TokenSymbol = { symbol: string; chainId: number };

type Token = TokenSymbol & { decimals: number; address: `0x${string}` };
```

| Option              | Description                                                                                                                                           |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialFromToken`  | Preferred token to swap from. Applied when the user holds a balance and the token is supported; otherwise the user's highest-value asset is selected. |
| `fallbackFromToken` | Token to show as the "from" side when the user holds no assets.                                                                                       |
| `initialToToken`    | Preferred token to swap to.                                                                                                                           |
| `defaultSlippage`   | Slippage tolerance in percent. Omitted or out-of-range values fall back to automatic slippage.                                                        |

**Returns:**

```ts theme={null}
{
  txHash: `0x${string}`;              // Transaction hash of the swap
  from: Token & { amount: string };   // Token sold, with the amount sold
  to: Token & { amount: string };     // Token bought, with the amount received
}
```

`from.amount` is what the user sold and `to.amount` is what they received.

<Warning>
  Both amounts are **base-unit integer strings** (smallest denomination), not human-readable decimals. Divide by `10 ** decimals` before displaying — printing `amount` directly shows `1000000` for 1 USDC.
</Warning>

**Usage:**

```ts theme={null}
import { formatUnits } from "viem";

try {
  const result = await airService.showSwapUI({
    initialFromToken: { symbol: "USDC", chainId: 8453 },
    defaultSlippage: 0.5,
  });

  const sold = formatUnits(BigInt(result.from.amount), result.from.decimals);
  const received = formatUnits(BigInt(result.to.amount), result.to.decimals);

  console.log("Swap completed! Transaction hash:", result.txHash);
  console.log(`Swapped ${sold} ${result.from.symbol}`);
  console.log(`Received ${received} ${result.to.symbol}`);
} catch (error) {
  console.error("Swap failed:", error);
}
```

**What happens during swap:**

1. Opens the swap interface
2. User selects token and amount to swap
3. User confirms the swap transaction
4. Returns the transaction hash upon successful completion

**Requirements:**

* User must be logged in

**Important Notes:**

* **Experimental feature**: This method is marked as experimental and may change in future versions
* **Chain support**: Currently only supported on Base network
* **User experience**: Opens a full swap interface with token selection, amount input, and slippage settings.
* **Advanced control**: For more control over the swap flow, use the RPC method `air_getSwapQuote` and `air_sendSwapTransaction` to specify exact token addresses, amounts, and slippage settings

## On-Ramp Interface

### showOnRampUI()

Opens the AIR Kit on-ramp interface, allowing users to purchase cryptocurrency with fiat currency.

**Method Signature:**

```ts theme={null}
public async showOnRampUI(options: {
  displayCurrencyCode: string;
  targetCurrencyCode?: string;
}): Promise<void>
```

**Parameters:**

```ts theme={null}
{
  displayCurrencyCode: string; // Fiat currency code (e.g., "USD", "EUR")
  targetCurrencyCode?: string; // Optional target cryptocurrency (e.g., "ETH", "USDC")
}
```

**Usage:**

```ts theme={null}
try {
  await airService.showOnRampUI({
    displayCurrencyCode: "USD",
    targetCurrencyCode: "USDC"
  });
  console.log("On-ramp interface opened");
} catch (error) {
  console.error("Failed to open on-ramp:", error);
}
```

**What happens during on-ramp:**

1. Opens the on-ramp interface
2. User selects payment method and amount
3. User completes the fiat-to-crypto purchase
4. Cryptocurrency is deposited to their wallet

**Requirements:**

* User must be logged in

**Important Notes:**

* **Experimental feature**: This method is marked as experimental and may change in future versions
* **No return value**: This method doesn't return a transaction hash as the purchase is handled by the on-ramp provider
* **Currency support**: Supported currencies depend on the on-ramp provider configuration