> 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/getting-started/readme.md).

# Overview

`@osero/client` is the TypeScript SDK Osero uses to integrate with the Sky/Spark PSM stack. It provides a single, unified API for minting and redeeming USDS and sUSDS on every chain where Sky/Spark runs a PSM, handling chain-specific routing, contract calls, and transaction sequencing so callers don't have to.

It does **not** handle gas sponsorship, balance/allowance pre-flight checks, or anything beyond the transactions described in the returned `ExecutionPlan`.

***

## Design principles

The SDK is built around three ideas:

{% stepper %}
{% step %}
**Separation of "what" from "how"**

Actions (what to do) are pure functions that return an `ExecutionPlan`, a wallet-agnostic description of the transactions required. Adapters (how to sign) are the only piece that touches a real wallet. Built-in adapters ship for **viem**, **ethers v6**, and **Privy server wallets**; the plan is plain data, so integrators that need to broadcast through a relayer, a 4337 bundler, or their own pipeline can flatten it and write their own send loop.
{% endstep %}

{% step %}
**Functional error handling**

Every action returns a `ResultAsync` from [neverthrow](https://github.com/supermacro/neverthrow). Errors are fully typed variants covering user rejections, validation failures, and RPC errors — not thrown exceptions. This makes error handling explicit, composable, and impossible to accidentally swallow.
{% endstep %}

{% step %}
**Preview before you commit**

Every action that moves funds has a matching `preview` helper that returns the expected output amount as a quoted `bigint` before any transaction is built or sent. This allows platforms to show users what they will receive before asking them to sign anything.
{% endstep %}
{% endstepper %}

***

## Package structure

| Import path             | Contents                                                                          |
| ----------------------- | --------------------------------------------------------------------------------- |
| `@osero/client`         | `OseroClient`, balance helpers, chain/token exports                               |
| `@osero/client/actions` | `mintUsds`, `mintSUsds`, `redeemUsds`, `redeemSUsds` and matching preview helpers |
| `@osero/client/viem`    | `sendWith` adapter for viem wallets                                               |
| `@osero/client/ethers`  | `sendWith` adapter for ethers v6 signers                                          |
| `@osero/client/privy`   | `sendWith` adapter for Privy server wallets                                       |

***

## Supported chains & tokens

The SDK exposes two support surfaces with different scopes:

* **On-chain actions** (`mintUsds`, `mintSUsds`, `redeemUsds`, `redeemSUsds`) — limited to chains where Sky/Spark run a PSM. Driven by `SUPPORTED_CHAIN_IDS`, the SDK's source of truth; new chains require an `@osero/client` release.
* **Swap API** (`OseroApiClient`) — a wider set of chains and stablecoins swappable to/from the Ethereum sUSDS vault, with cross-chain routing (CCIP, LayerZero, Relay, or Stargate) handled by the API. Driven by `OSERO_API_CHAINS` and `OSERO_API_COUNTER_ASSETS`.

#### On-chain actions

| Chain            | Chain ID | PSM contract   | Status |
| ---------------- | -------- | -------------- | ------ |
| Ethereum Mainnet | 1        | UsdsPsmWrapper | Live   |
| OP Mainnet       | 10       | PSM3           | Live   |
| Unichain         | 130      | PSM3           | Live   |
| Base             | 8453     | PSM3           | Live   |
| Arbitrum One     | 42161    | PSM3           | Live   |

Every chain above carries the same three tokens, registered with canonical addresses in the SDK:

* **USDC** — Circle USDC, native issuance (not bridged USDC.e), 6 decimals
* **USDS** — Sky stablecoin, 18 decimals
* **sUSDS** — ERC-4626 savings vault on USDS (accrues the SSR), 18 decimals

| Chain        | USDC                                         | USDS                                         | sUSDS                                        |
| ------------ | -------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
| Ethereum     | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` | `0xdC035D45d973E3EC169d2276DDab16f1e407384F` | `0xa3931d71877C0E7a3148CB7Eb4463524FEc27fbD` |
| OP Mainnet   | `0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85` | `0x4F13a96EC5C4Cf34e442b46Bbd98a0791F20edC3` | `0xb5B2dc7fd34C249F4be7fB1fCea07950784229e0` |
| Unichain     | `0x078D782b760474a361dDA0AF3839290b0EF57AD6` | `0x7E10036Acc4B56d4dFCa3b77810356CE52313F9C` | `0xA06b10Db9F390990364A3984C04FaDf1c13691b5` |
| Base         | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | `0x820C137fa70C8691f0e44Dc420a5e53c168921Dc` | `0x5875eEE11Cf8398102FdAd704C9E96607675467a` |
| Arbitrum One | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` | `0x6491c05A82219b8D1479057361ff1654749b876b` | `0xdDb46999F8891663a8F2828d25298f70416d7610` |

#### Swap API

The swap API routes any supported counter asset to or from the single vault asset, **sUSDS on Ethereum** (`ethereum:susds`). Supported pairs are strictly counter asset ↔ sUSDS; counter-to-counter swaps are not supported. Counter-asset addresses are not pinned in the SDK — the API (`/swap/assets`) is the source of truth for canonical deployments.

| Chain        | Chain ID | Chain key     | Swappable assets                                                     |
| ------------ | -------- | ------------- | -------------------------------------------------------------------- |
| Ethereum     | 1        | `ethereum`    | USDC, USDe, AUSD, GHO, PYUSD, RLUSD, USDD, USDG, USDT, USDtb, frxUSD |
| OP Mainnet   | 10       | `optimism`    | USDC, USDe                                                           |
| BNB Chain    | 56       | `bnb`         | USDe                                                                 |
| Unichain     | 130      | `unichain`    | USDC                                                                 |
| Polygon      | 137      | `polygon`     | USDC                                                                 |
| Monad        | 143      | `monad`       | USDC                                                                 |
| HyperEVM     | 999      | `hyperevm`    | USDC, USDe                                                           |
| Base         | 8453     | `base`        | USDC, USDe                                                           |
| Plasma       | 9745     | `plasma`      | USDe                                                                 |
| Arbitrum One | 42161    | `arbitrum`    | USDC, USDe, PYUSD                                                    |
| Avalanche C  | 43114    | `avalanche_c` | USDC, USDe                                                           |
| Linea        | 59144    | `linea`       | USDC, USDe                                                           |
| Berachain    | 80094    | `berachain`   | USDC.e, USDe                                                         |

Asset IDs follow the `<chainKey>:<tokenKey>` convention (e.g. `base:usdc`, `plasma:usde`). USDC is native Circle issuance everywhere except Berachain, which uses canonical bridged `USDC.e`.

***

## Requirements

* Node.js 18+
* TypeScript 5.x (strict mode recommended)
* `viem` v2 (required peer dependency)
* `ethers` v6 (optional, only needed for the ethers adapter)

***

## Next steps

* [Installation](/osero-sdk/getting-started/installation.md)
* [Quick Start](/osero-sdk/getting-started/quick-start.md)
* [Actions reference](/osero-sdk/core-concepts/actions.md)
* [Error Handling](/osero-sdk/reference/error-handling.md)
* [The Execution Plan model](/osero-sdk/core-concepts/execution-plan.md)


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.osero.org/osero-sdk/getting-started/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.