Looking for the full documentation? Visit the complete Osero Earn docs for the full SDK reference.
@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
- 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.
- 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.
- 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/clientand its requiredviempeer dependency- A production RPC endpoint for every chain you use
- Optional:
ethersfor the ethers v6 adapter
How It Works
Each mint or redeem flow follows the same three-layer pattern:- Preview: A read-only helper such as
previewMintSUsdsquotes the expected output as abigint. It needs no wallet or sender. - Action:
mintUsds,mintSUsds,redeemUsds, orredeemSUsdsbuilds a typed, wallet-independentExecutionPlan. Building a plan may perform live RPC reads to obtain fees, vault previews, or PSM quotes. - Adapter:
sendWith(...)executes the plan through a supported signer: a Para-backed viem wallet client, or an ethers v6 signer.
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:
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: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 rawbigint. They require only chainId and amount.
Step 5: Mint sUSDS
On user confirmation, build the plan and send it through the Para-backed wallet client:mintSUsds produces an Erc20ApprovalRequired plan with two transactions:
- Approve USDC to PSM3.
- Swap USDC for sUSDS through PSM3.
MultiStepExecution route:
- Approve USDC to
UsdsPsmWrapper. - Convert USDC to USDS.
- Approve USDS to the sUSDS vault.
- 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 optionalreceiver. 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.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.Broadcasting with Other Signers
Osero’s action API is adapter-independent, but each request and plan is bound to itssender. 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.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 usesneverthrow for its normal action, preview, balance, and adapter workflows. Check the final ResultAsync result after chaining:
OseroClient.getPublicClient(unsupportedChain)throwingUnsupportedChainErrorwhen called directly.- viem
sendWith(walletClient)throwing if the client has no attached account or chain. - Invalid non-integer or out-of-range
slippageBpsreachingapplySlippageand throwingRangeErrorin affected L2 paths.
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 extendOseroError, but the exact error union depends on the helper and adapter being used.
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.