Skip to content

Documentation

Docs

Otolith keeps a portfolio near a target split without ever holding the funds. These pages say how, in plain terms first and then in the contracts’ own.

How Otolith works for the person who owns the account: what it does, what you set, and what stops it from doing anything else.

NetworkStellar testnet
PairXLM and USDC
DirectionSells XLM, buys USDC
CustodyYour account only

01User

What Otolith is

Otolith keeps a two-asset portfolio close to the split you choose. You pick a target share of USDC, the rest stays in XLM, and when the portfolio drifts past a band you set, a rebalance sells some XLM into USDC to bring it back.

It does this without taking custody. Your funds sit in your own smart account on Stellar, secured by a passkey. The rule that allows rebalancing lives on that account as a contract, with limits you signed once. Otolith the company holds no balance of yours and cannot move one.

Testnet only

Otolith runs on Stellar testnet today. The assets are testnet tokens with no value, and the contracts are not deployed on mainnet.

What it covers today

  • One pair: XLM and USDC.
  • One direction: a rebalance only ever sells XLM and buys USDC.
  • One policy per account at a time.
  • Passkey accounts. There is no seed phrase and no browser extension.

Some things are not built yet: recovering an account if you lose your passkey, a full activity history beyond the recent window the network keeps queryable, and portfolios of more than two assets.

02User

How it keeps your portfolio balanced

Your target is a single number: the share of the portfolio you want held in USDC. A target of 40% USDC means 60% XLM. Both holdings are valued in dollars using a price oracle, so the split is a split by value, not by token count.

Drift is how far your current USDC share sits from the target. The drift band is how much drift is tolerated before a rebalance is worth doing. Inside the band, nothing happens. Past it, a rebalance becomes due.

Inside the band. No rebalance is due.
Past the band. A rebalance is due.

One direction only

A rebalance only ever sells XLM to buy USDC. It acts when you hold too little USDC. If you hold more USDC than the target, however far past the band, nothing is triggered: the contracts never sell USDC. The dashboard labels that state Above target, not Past band.

How big the trade is

Nobody chooses the amount, including whoever triggers the rebalance. The rebalancer contract works out the trade that would close the drift exactly, checks it against the pool’s real quote, and shrinks it if the pool would return more than the oracle implies. After the swap it checks where the portfolio landed. If the result is more than 0.5 percentage points past your target, the whole transaction is reverted and nothing changes. The guarantee is a bounded overshoot, not an exact landing.

03User

Your account and passkey

Creating an account creates a passkey on your device and deploys a smart account that your passkey controls. The app walks through it in three stages: creating the passkey, preparing the account, then deploying and funding it on-chain. The deployment fee is paid by Otolith’s fee account, not by you, and a new testnet account is funded with testnet XLM.

A smart account is a contract that decides what counts as valid authorization. Yours has one rule from the start: your passkey can authorize anything. Your device keeps the private key and never shares it. Otolith sees a signature when you approve something, never the key.

Holding USDC

The account starts with XLM only. To hold USDC, send it to the account’s address. The address is shown on the dashboard and in Settings. The USDC the app uses is the testnet token listed under Deployed contracts in the technical guide.

No recovery yet

If you lose the device that holds your passkey, there is no way to regain the account today. Recovery is not built. Treat a testnet account as disposable, and do not rely on it for anything you cannot lose.

You can reconnect to an existing account from the dashboard by choosing the passkey you already have.

04User

Setting up a policy

Setup is three steps and one signature. Nothing is installed until the last one.

  1. 01
    Split. Choose your target split between XLM and USDC. Whatever share you give USDC is the target the contracts hold the portfolio to.
  2. 02
    Parameters. Sensible defaults are already set. Open Advanced settings to change the drift band, the slippage tolerance or the cooldown.
  3. 03
    Review and sign. Check the terms, then approve with your passkey. Otolith pays the network fee.
The three settings you can change, with their defaults and allowed ranges
SettingDefaultAllowed rangeWhat it does
Drift band2%0.10% to 20%How far the portfolio can drift before a rebalance is worth doing.
Slippage tolerance1%0.30% to 5%The most price impact a single rebalance trade may accept.
Cooldown1 hour5 minutes to 7 daysThe shortest time allowed between two rebalances.

The ranges are checked twice: the form rejects a value outside them before asking for a signature, and the policy contract rejects it again when the policy is installed. The contract is the authority.

What the cooldown trades off

A shorter cooldown keeps the portfolio closer to target but lets it trade more often, which costs more in fees and price impact. A longer one trades less. It also limits how often your account can be made to trade, which matters because anyone can trigger a rebalance.

What you do not set

Three more values are fixed by the app: no minimum trade size, no tip allowance, and a cost limit of 25%. They are stored with your policy but not shown in the form.

Setting up a policy adds a rule to your account with no signers and our policy contract attached. To change a policy, revoke it in Settings and set up a new one.

05User

How and when rebalances happen

Rebalancing is permissionless: anyone can submit it, and no owner signature is required. The contracts, not the person submitting, decide whether it is allowed. Otolith does not run a background bot today. A rebalance happens when someone triggers it, and the dashboard gives you a button to do exactly that.

When one is due

The dashboard checks all of these for you, and the rebalance panel says which one is holding things back:

  • Your portfolio holds less USDC than the target by more than the drift band.
  • The cooldown since your last rebalance has passed.
  • The oracle has a current price for both assets. The contracts refuse a price older than 10 minutes.
  • The trading pool can fill the trade within your slippage tolerance.

What a rebalance is

One atomic transaction. It reads both prices, works out the trade, swaps XLM for USDC through Soroswap, and checks the result. If any step fails, the whole transaction is reverted and your balances are exactly as they were. The fee is paid by Otolith’s keeper account, which is never a signer on your account.

A trade costs the pool’s fee of 0.3 percent, plus whatever price impact the pool applies, up to the slippage tolerance you set.

06User

Your funds and safety

Funds never leave your account. A rebalance swaps one of your assets for another and delivers the result back to your account. There is no step where Otolith, the keeper or anyone else receives your tokens.

What stops a rebalance from doing something else, and what enforces it:

Safety behaviors and what enforces each
BehaviorEnforced by
Only XLM can be sold, only USDC bought, only through the Soroswap router.The policy contract, on-chain.
The result must come back to your account, and the tokens must go to the real pool for the pair.The policy contract, on-chain.
The trade cannot be larger than the one that closes your drift.The policy contract, on-chain.
Price impact above your slippage tolerance is refused.The policy contract, from its own oracle read.
No rebalance inside the cooldown.The policy contract, on-chain.
A missing or stale price stops the rebalance.Both contracts, on-chain.
The policy cannot change your account or its other rules.The policy contract, on-chain.
Setting values outside the allowed ranges.The contract, and the form before it.
Asking you to confirm before you revoke.The interface only.

Revoking

Revoke removes the rule, and with it every future rebalance, in one passkey signature. Your balances stay where they are. The Settings page has the control, with a confirmation step.

What you still trust

  • The price oracle. The contracts bound how old a price may be, not whether it is right.
  • The trading pool. Your slippage tolerance caps how much a poor fill can cost you.
  • Your device and its passkey. Without a recovery path, losing it loses the account.

07User

Reading your dashboard

Portfolio value

The total in dollars, priced from the same oracle the contracts use, not from a market quote. If the oracle’s latest price is older than 10 minutes, the value is still shown, dated to when that price was published, with a note that the feed is delayed. If there is no price at all, it says the value is not available.

Allocation and drift

The ring shows how much you hold of each asset now against the target. Drift is your USDC share minus the target, so a negative figure means you hold less USDC than you want. The badge reads Within band, Past band or Above target. It is only marked as past the band while a rebalance is actually called for. With a delayed price the split is shown but no verdict is drawn.

Your policy

The terms you signed: target allocation, drift band, slippage tolerance and cooldown.

Rebalance

This panel is the authority on whether a rebalance can happen. It shows one of these:

  • Within the target band, so no rebalance is needed.
  • A rebalance is due, with the Rebalance now button.
  • A recent rebalance, so the cooldown is running.
  • The pool cannot support the trade safely, so Otolith holds off.
  • The live price is delayed or unavailable, so the status cannot be determined.

Balances, Activity and Explore

Balances lists what the account holds. Activity lists recent rebalances read directly from the public network, with a note of how far back the search reached. It is recent activity, not the full history, and it links to the full record on stellar.expert. Explore shows the two supported assets and their live oracle prices.

08User

FAQ

Is this on mainnet?

No. Otolith runs on Stellar testnet only. The assets have no value.

Can Otolith take my funds?

No. Funds stay in your account. The policy that allows rebalancing can only approve one narrow swap from XLM to USDC, delivered back to the same account. Everything else, including changing the account, needs your passkey.

Who can trigger a rebalance?

Anyone. They cannot choose the size or the assets, and the contracts refuse anything outside your policy.

My portfolio is past the band and nothing happened. Why?

Nobody has triggered a rebalance yet, since there is no background bot. If you trigger one and it is refused, the rebalance panel names the reason: the cooldown is running, the oracle price is delayed, or the pool cannot fill the trade within your tolerance. If you hold more USDC than the target, nothing will happen, because a rebalance never sells USDC.

Why only XLM and USDC, and only selling XLM?

The first version is deliberately narrow so the safety logic stays small and checkable. Portfolios of more than two assets are planned, not built.

How do I change my policy?

Revoke it in Settings, then set up a new one. A policy cannot be edited in place.

What does it cost me?

The network fees for creating the account, installing or revoking a policy, and submitting a rebalance are paid by Otolith on testnet. A trade itself costs the pool’s 0.3 percent fee plus price impact, up to your slippage tolerance.

What if I lose my passkey?

Recovery is not built yet, so the account cannot be signed for again. Your funds would stay in the account, where only that passkey can move them.

Why does the dashboard say the price is delayed?

The oracle on testnet sometimes stops publishing for a while. The contracts will not act on a price older than 10 minutes, so rebalances pause, and the dashboard shows the last published price with its time instead of pretending it is current.

Where is my full history?

Activity shows the recent window the public network keeps queryable, and says how far back it reached. For everything older, follow the link to your account on stellar.expert.