> For the complete documentation index, see [llms.txt](https://docs.osero.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.osero.org/osero-sdk/reference/examples.md).

# Examples

The `@osero/examples` package contains a set of runnable, self-contained scripts that demonstrate every major SDK flow. Each example previews the operation, builds an `ExecutionPlan`, and either inspects it or broadcasts it through a wallet adapter.

A github repo with implementation examples may be accessed [here](https://github.com/osero-io/kit/tree/main/examples)

## Getting started

```bash
# From the repo root
pnpm install

# Copy the example env file and fill in your values
cp examples/.env.example examples/.env
```

{% hint style="warning" %}
At minimum, set `PRIVATE_KEY` in `examples/.env`. Use a **disposable wallet funded with small amounts** — the examples broadcast real transactions. The Privy example uses the `PRIVY_*` variables instead of `PRIVATE_KEY`.
{% endhint %}

```bash
# Example .env
PRIVATE_KEY=0x...

# Optional: custom RPC endpoints (strongly recommended)
RPC_URL_MAINNET=https://eth.llamarpc.com
RPC_URL_BASE=https://mainnet.base.org
RPC_URL_ARBITRUM=https://arb1.arbitrum.io/rpc
RPC_URL_OPTIMISM=https://mainnet.optimism.io
RPC_URL_UNICHAIN=https://mainnet.unichain.org

# Required only for the Privy example (privy:mint-usds)
PRIVY_APP_ID=...
PRIVY_APP_SECRET=...
PRIVY_WALLET_ID=...
PRIVY_WALLET_ADDRESS=0x...
# Only if your Privy app requires request authorization
PRIVY_AUTHORIZATION_PRIVATE_KEY=

```

## Available examples

### Dry run — no wallet or funds required

Builds a `mintSUsds` `ExecutionPlan` on Base and prints the full transaction sequence without broadcasting anything. A good first step to verify your setup.

```bash
pnpm --filter @osero/examples dry-run:inspect-plan
```

### viem examples

**Mint USDS on Base** — USDC → USDS, single approve + PSM3 swap.

```bash
pnpm --filter @osero/examples viem:mint-usds
```

**Mint sUSDS on Ethereum Mainnet** — USDC → sUSDS, four-transaction `MultiStepExecution`.

```bash
pnpm --filter @osero/examples viem:mint-susds-mainnet
```

**Redeem sUSDS on Base** — sUSDS → USDC.

```bash
pnpm --filter @osero/examples viem:redeem-susds
```

**Round trip on Base** — USDC → sUSDS → USDC, full round-trip. Demonstrates balance tracking with `getTokenBalances` and `getSUsdsBalance`.

```bash
pnpm --filter @osero/examples viem:roundtrip
```

### ethers v6 examples

**Mint USDS on Base** — same as the viem equivalent, but through an ethers v6 `Wallet`.

```bash
pnpm --filter @osero/examples ethers:mint-usds
```

**Round trip on Base** — full round-trip through an ethers v6 `Wallet`.

```bash
pnpm --filter @osero/examples ethers:roundtrip
```

### Privy examples

**Mint USDS on Base** — same flow as the viem equivalent, but signed and broadcast by a Privy server wallet. Requires the `PRIVY_*` variables above instead of `PRIVATE_KEY`.

```bash
pnpm --filter @osero/examples privy:mint-usds
```

## Example structure

```
examples/
├── src/
│   ├── shared/
│   │   ├── env.ts          # Loads PRIVATE_KEY + RPC URLs from process.env
│   │   └── format.ts       # Pretty-printing helpers
│   ├── dry-run/
│   │   └── inspect-plan.ts
│   ├── viem/
│   │   ├── mint-usds.ts
│   │   ├── mint-susds-mainnet.ts
│   │   ├── redeem-susds.ts
│   │   └── roundtrip-usdc-susds.ts
│   └── ethers/
│   │   ├── mint-usds.ts
│   │   └── roundtrip-usdc-susds.ts
│   └── privy/
│       └── mint-usds.ts

```

## The mental model in \~40 lines

The roundtrip example is the clearest illustration of how the three SDK layers work together:

```typescript
import { OseroClient, getTokenBalances } from '@osero/client';
import { mintSUsds, redeemSUsds, previewMintSUsds } from '@osero/client/actions';
import { sendWith } from '@osero/client/viem';

// 1. Create the client
const client = OseroClient.create({ transports: { 8453: http(RPC_URL_BASE) } });

// 2. Preview: quote expected sUSDS before building a plan
const quote = await previewMintSUsds(client, { chainId: 8453, amount });
console.log('Expected sUSDS:', quote.value);

// 3. Read balances before
const before = await getTokenBalances(client, { chainId: 8453, account });

// 4. Mint: action → plan → send
await mintSUsds(client, { chainId: 8453, amount, sender: account })
  .andThen(sendWith(wallet));

// 5. Read balances after mint
const afterMint = await getTokenBalances(client, { chainId: 8453, account });

// 6. Redeem: reverse the flow
const susdsBalance = afterMint.value.sUSDS;
await redeemSUsds(client, { chainId: 8453, amount: susdsBalance, sender: account })
  .andThen(sendWith(wallet));

// 7. Final balances
const final = await getTokenBalances(client, { chainId: 8453, account });
```

This example surfaces all three SDK layers in sequence:

* **Preview helpers** — quote without building a plan
* **Actions** — build wallet-agnostic `ExecutionPlan`s
* **Adapters** — broadcast plans through a real wallet
* **Balance helpers** — track token balances across the flow


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.osero.org/osero-sdk/reference/examples.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.