Skip to main content
Looking for the full documentation? Visit the complete Osero Earn docs for the full SDK reference.
Combine Para’s wallet infrastructure with the Osero Earn Integration SDK (@osero/client) to let users convert USDC into USDS or the yield-bearing sUSDS savings token, and redeem either asset back to USDC, from a Para-powered wallet. Users can interact through your application’s interface without installing a browser extension or managing a seed phrase.

What You’ll Learn

This walkthrough covers the Osero Earn lifecycle: installing the SDK alongside Para, initializing a client, previewing a quote, minting and redeeming on supported chains, reading balances, inspecting execution plans, and using alternate signer adapters.
Version scope: The API and supported-chain details below target @osero/client@0.8.0, the npm latest release at the time of writing. Check SUPPORTED_CHAIN_IDS at runtime when upgrading.

Why Combine Para and Osero Earn

Example Use Cases

  1. Consumer Earn Product: Users deposit USDC into a Para wallet and mint sUSDS for yield, entirely inside your app’s UI, with no protocol interaction visible to them.
  2. Fintech Stablecoin Rails: Embed USDS mint/redeem flows in a fintech app using Para’s white-label wallet onboarding, giving users a stable, non-yield-bearing balance alongside an optional yield toggle.
  3. Treasury Automation: Automate treasury USDS/sUSDS positions from Para wallets with programmable mint and redeem rules, previewing expected output before every rebalance.

What You Need

  • An authenticated Para session with an EVM wallet
  • A supported EVM chain
  • @osero/client and its required viem peer dependency
  • A production RPC endpoint for every chain you use
  • Optional: ethers for the ethers v6 adapter

How It Works

Each mint or redeem flow follows the same three-layer pattern:
  1. Preview: A read-only helper such as previewMintSUsds quotes the expected output as a bigint. It needs no wallet or sender.
  2. Action: mintUsds, mintSUsds, redeemUsds, or redeemSUsds builds a typed, wallet-independent ExecutionPlan. Building a plan may perform live RPC reads to obtain fees, vault previews, or PSM quotes.
  3. Adapter: sendWith(...) executes the plan through a supported signer: a Para-backed viem wallet client, or an ethers v6 signer.
The plan is created before the signer is invoked, so your application can inspect its transactions before prompting the user. A plan is independent of the wallet library, but it is still bound to the request’s sender: the selected signer must control the plan’s from address and be connected to the target chain where applicable.

Supported Chains

The direct Osero Earn actions in @osero/client@0.8.0 support: Use the SDK’s registry as the source of truth:
The hosted Osero API may recognize additional chains. That does not imply support in the direct Earn actions described in this guide.

Step-by-Step Integration

Step 1: Install Dependencies

This walkthrough uses Para’s minimal web SDK and the low-level viem integration directly:
viem is a required peer dependency of @osero/client. Osero uses it to encode calldata and create public clients even when another adapter broadcasts transactions. Optional adapters:
@osero/client is ESM, is authored in strict TypeScript, and includes type declarations. No additional @types package is required.
If your React application already uses @getpara/react-sdk and ParaProvider, reuse the authenticated Para instance from that integration instead of constructing a second independent client. Para’s current React guidance also provides useParaViemClient for hook-based applications.

Step 2: Initialize Para and Osero

The code below creates the SDK clients, but it does not implement Para login. Complete your application’s Para authentication flow and ensure the user has an EVM wallet before creating the viem account. Use authenticated RPC endpoints in production. Public RPC endpoints are commonly rate-limited.

Step 3: Create the Para-Backed viem Wallet

Run this only after Para authentication has completed and an EVM wallet exists:
The older createParaAccount(para) alias and positional createParaViemClient(para, config) overload still exist in @getpara/viem-v2-integration@3.11.0, but they are deprecated. You do not need to create a separate viem publicClient for Osero reads. OseroClient creates and caches its own public clients using the transports supplied to OseroClient.create.

Step 4: Preview an sUSDS Mint

Preview helpers return the expected output as a raw bigint. They require only chainId and amount.
A preview is not a guaranteed execution result. The relevant on-chain state can change between previewing, building the plan, and mining the transaction.

Step 5: Mint sUSDS

On user confirmation, build the plan and send it through the Para-backed wallet client:
On Base and the other supported L2s, mintSUsds produces an Erc20ApprovalRequired plan with two transactions:
  1. Approve USDC to PSM3.
  2. Swap USDC for sUSDS through PSM3.
On Ethereum Mainnet, it produces a four-transaction MultiStepExecution route:
  1. Approve USDC to UsdsPsmWrapper.
  2. Convert USDC to USDS.
  3. Approve USDS to the sUSDS vault.
  4. Deposit USDS and deliver sUSDS to the receiver.
sendWith(walletClient) executes the transactions in order and waits for each required confirmation before continuing. To receive non-yield-bearing USDS instead, use mintUsds. redeemUsds follows the same action → plan → adapter pattern in the opposite direction.

Step 6: Send Output to Another Address

Each action accepts an optional receiver. The signer still pays with assets owned by sender, while the resulting asset is delivered to receiver.
On Ethereum Mainnet, sender temporarily receives the intermediate USDS even when receiver differs. Any USDS dust left after the vault deposit remains with sender.
Setting receiver does not authorize that address to sign for sender, and it does not move custody of the signing wallet.

Step 7: Redeem sUSDS to USDC

Step 8: Read Balances

Osero exposes helpers for USDC, USDS, and sUSDS on every supported direct-action chain.
Reading balances before and after execution lets you measure the exact token delta received. The final transaction hash alone does not communicate the exact amount received.

Broadcasting with Other Signers

Osero’s action API is adapter-independent, but each request and plan is bound to its sender. Build the request with the address controlled by the selected signer.

Inspecting an Execution Plan Before Signing

Actions build their plans before invoking a signer, but they are not pure functions: they can perform live RPC reads and return transport errors.
The transaction data is encoded calldata. Decode it against the relevant ABI before presenting it as a human-readable signing explanation. An execution plan is a discriminated union. Pattern-match on plan.__typename when handling the shapes directly: For @osero/client@0.8.0:

Error Handling

Osero uses neverthrow for its normal action, preview, balance, and adapter workflows. Check the final ResultAsync result after chaining:
Do not describe the entire package as having “no thrown exceptions.” Public synchronous or rejected-promise paths include:
  • OseroClient.getPublicClient(unsupportedChain) throwing UnsupportedChainError when called directly.
  • viem sendWith(walletClient) throwing if the client has no attached account or chain.
  • Invalid non-integer or out-of-range slippageBps reaching applySlippage and throwing RangeError in affected L2 paths.
Validate application input before calling the SDK. In particular, keep slippageBps an integer in the supported range and wrap the full action/adapter expression in try/catch.

Errors relevant to the direct Earn flow

All Osero error classes extend OseroError, but the exact error union depends on the helper and adapter being used.
ethers caveat: ethers v6 throws CALL_EXCEPTION from TransactionResponse.wait() for a mined status-0 transaction. In @osero/client@0.8.0, the ethers adapter can map that rejection to UnexpectedError instead of TransactionError. Inspect UnexpectedError.cause for an ethers receipt or transaction hash.
ApiRequestError is another exported OseroError subclass, but it belongs to the separate hosted Osero API client rather than the direct Earn flow shown here.
Want more detail? Check out the full Osero Earn docs for complete SDK reference and guides.