` once.
### How much can prices surge?
The congestion multiplier is capped at 2x, and prepaid OZ credit is exempt from it entirely.
## Related
- [Agent API Overview](/agents/overview/)
- [Endpoint Catalog](/agents/endpoints/)
- [Integration Notes](/agents/integration/)
---
# Andhakara
> Andhakara is a collectible card collection on vibe.market, trading as ANKR on Base, with an In Oz We Trust expansion.
URL: https://docs.ozmium.org/also/andhakara/
Markdown: https://docs.ozmium.org/also/andhakara/index.md
Keywords: andhakara ankr, gamefi collectible cards base, vibe market base, in oz we trust expansion, onchain trading cards
Updated: 2026-07-28
**[Andhakara](https://vibechain.com/market/andhakara?ref=W2YQQ8FH39QD)** trades as **ANKR** on
[vibe.market](https://vibe.market), a Base-native platform for collectible card collections. Packs
open onchain, card metadata and pack odds are published before purchase, and every pull, trade, and
listing settles as a Base transaction anyone can verify. The platform's mechanics, contracts, and
developer interfaces are documented at [docs.vibechain.com](https://docs.vibechain.com/docs/vibemarket),
including the [contract interfaces](https://docs.vibechain.com/docs/vibemarket/developers/interfaces)
an agent would build against.
The **In Oz We Trust** expansion connects the collection to the wider Ozmium world, and the cards
themselves trade on the open market: the collection is listed on
[OpenSea](https://opensea.io/collection/andhakara) as well as on vibe.market itself.
## The Cards
## Watch It
{{video:andhakara-in-oz-we-trust|In Oz We Trust, the collectible card expansion.}}
{{video:andhakara-vibe-market-alpha|Vibe Market Alpha, featuring Andhakara.}}
## Pack Economics, Measured
The mechanics are contract reads rather than marketing, so the arithmetic is checkable before you buy
anything.
| Input | Where It Comes From |
|---|---|
| Pack Price | `getMintPrice(n)` on the drop contract |
| Entropy Fee | `getEntropyFee()`, the randomness cost, added on top |
| Card Value | `getTokenSellQuote()` against the bonding curve |
| Platform Fee | Roughly 7.5 percent on the round trip, split between creator, referrer, and platform |
Which gives the expected value of opening one pack:
```
EV = sum( P(rarity) x payout(rarity) ) x (1 - fee) - packCost - entropyFee - gas
```
The house edge is explicit rather than hidden. A 7.5 percent round trip on a bonding curve is the
business model, stated in the open, and a pack is only worth opening when the rarity distribution
pays for it. That is measurable, and it is the reason the numbers above are contract calls rather
than claims.
Cards come in five tiers, read from `getTokenRarity`: Common, Uncommon, Rare, Epic, and Legendary.
Both Andhakara contracts are live on Base as minimal-proxy clones, so every figure here can be read
straight from the chain:
| Contract | Address |
|---|---|
| Drop | [`0x6b86b5fdb2be7aa5680959aba268963876dbb091`](https://basescan.org/address/0x6b86b5fdb2be7aa5680959aba268963876dbb091) |
| Token | [`0xf3d04c612643a98ac485458053c0a9fe6b6d6a53`](https://basescan.org/address/0xf3d04c612643a98ac485458053c0a9fe6b6d6a53) |
The referrer share of that 7.5 percent is why the links on this page carry a referral code. Opening a
pack through them costs you nothing extra, and routes the referrer portion of a fee you were paying
anyway.
## What Makes a Card Collection Onchain
Physical trading cards have an authentication problem that has never really been solved: grading is a
service you pay for, and provenance is a story somebody tells you. Onchain, both are properties of
the record.
| Property | How It Works |
|---|---|
| Pack Odds | Published before purchase, not discovered after. |
| Provenance | Every mint, pull, and transfer is a Base transaction. |
| Ownership | Held in your own wallet, tradeable without asking anyone. |
| Scarcity | Enforced by the contract rather than by a printer's word. |
## Where It Sits
Andhakara is a collection, not a financial product, and holding a card entitles you to nothing beyond
the card. Read [Terms And Risk](/company/terms/) before buying anything onchain, here or anywhere
else.
## Related
- [Bard: The Theremini App](/also/bard/)
- [Ozmium Labs](/also/labs/)
- [OZ Token](/token/oz/)
---
# Risk
> Leveraged perpetuals on Gains Network gTrade through Ozmium - sizing against real volatility, liquidation mechanics, managing a live position, and honest risk.
URL: https://docs.ozmium.org/guides/leverage/
Markdown: https://docs.ozmium.org/guides/leverage/index.md
Keywords: leveraged perpetuals base, gains network gtrade, 200x leverage usdc collateral, liquidation price perpetual, volatility position sizing
Updated: 2026-07-27
Leverage is the highest-risk thing you can do in this app, so this page is going to spend more time on
how it goes wrong than on how it goes right.
Leveraged perpetuals come from [Gains Network gTrade](https://gains.trade), using USDC as collateral. You post margin, pick a
direction and a multiplier, and hold a position that has no expiry date. Position size is simply your
margin times your leverage.
## The Arithmetic You Cannot Argue With
:::danger Leverage math is not negotiable
At 10x, a 10 percent move against you erases your margin. At 50x it only takes 2 percent, and at 200x
it takes half a percent, which is well inside the ordinary daily noise of almost every market listed
here. None of that is a caveat about this interface or a thing we could soften if we felt like it. It
is arithmetic, and the chain applies it without asking anybody.
:::
| Leverage | Adverse Move that Erases Margin |
|---|---|
| 2x | 50% |
| 5x | 20% |
| 10x | 10% |
| 25x | 4% |
| 50x | 2% |
| 100x | 1% |
| 200x | 0.5% |
Figures exclude spread, opening fees, and rollover, all of which move the real liquidation point
closer.
## Six Asset Classes
Ozmium surfaces the tradeable [gTrade](https://gains.trade) markets across:
- Crypto
- Forex majors and crosses
- Energy - oil, gas, uranium
- Metals - gold, silver, copper, miners
- Indices
- Stocks
Each market has its own maximum leverage and spread, readable at `GET /v1/risk/pairs`.
Read the caveats in that feed rather than the headlines. The multi-timeframe entries say plainly that
timeframes are correlated, so agreement across them is confluence rather than independent
confirmation. That is the sort of qualification most signal products leave out.
## Sizing against Real Volatility
The most useful thing in this whole app is not the order ticket. It is the sizing read sitting
underneath it, because the ticket will happily let you do something stupid and the sizing read is what
talks you out of it.
**Suggested leverage** comes from the market's recent realized volatility rather than from a round
number that felt right. A market that routinely swings 6 percent in a day simply cannot carry the same
multiplier as one that moves 0.6 percent, and pretending otherwise is how positions are liquidated.
**Survival sizing** answers the question you actually care about: given how far this market has really
moved lately, what size gets through a move like that without being liquidated? Treat it as a ceiling
rather than a promise. Markets exceed their own history all the time, and a past range has never once
been obliged to contain a future price.
**Liquidation price** is on the ticket before you sign.
## Opening a Position
1. Pick the market and direction.
2. Set margin in USDC and choose leverage. Check the suggested leverage and the survival read.
3. Set a take profit and a stop loss. Do this at open, not later.
4. Review the liquidation price. If it sits inside a move you consider likely, the size is wrong.
5. Approve USDC if needed, then sign.
Ozmium handles the exact scaling gTrade requires - leverage at 1e3, prices at 1e10, USDC at 6
decimals, slippage at 1e3. Getting these wrong is the most common cause of a reverted or wildly
mis-sized position when integrating gTrade directly.
## Managing an Open Position
You can modify a live position without closing it:
- **Move a stop to breakeven** once the trade is working.
- **Re-aim a target** as conditions change.
- **Change leverage.** Decreasing leverage requires a collateral top-up, and Ozmium prepends the
USDC approve automatically.
Managing beats paying a full round trip to adjust. Closing and reopening costs spread, fees, and
execution risk.
## Costs that Accrue
| Cost | When |
|---|---|
| Spread | At Open and at Close |
| Opening Fee | At Open |
| Rollover / Funding Fee | Continuously while the position is open |
| Gas | Per Transaction |
Rollover matters. The displayed liquidation price excludes rollover and borrow fees, which means your
real liquidation point drifts closer over time on a position you leave alone.
## Liquidation
Gains liquidates a position when its margin can no longer cover losses. This is enforced onchain by
the protocol. Ozmium does not liquidate anyone, cannot stop a liquidation, and has no discretion in
the matter.
A stop loss is not a guarantee either. In a fast gap, the fill can be worse than the stop, or the
position can reach liquidation before the stop executes.
## Signal and Marker Feed Disclosure
Ozmium publishes multi-indicator technical reads - RSI, MACD, Bollinger bands, VWAP, trend, candle
patterns - reduced to a directional bias and a conviction score. It also publishes ranked long and
short setups across every category.
The app says it plainer than any documentation would:
> Ozwald is calibrating signals. You can still look at the experimental ones, but understand they are
> speculative amusement and not finished or tested.
Signals ship **off**. A wallet has to be connected before experimental signals can be turned on, which
is a deliberate speed bump rather than an oversight. Nothing here is financial advice, there is no
established out-of-sample edge, and the interface is not going to pretend otherwise while you are
looking at a 200x market.
## Sharing a Result
Closed positions can be rendered as a share card carrying the market, direction, leverage, entry
price, mark price, and result, with the wallet shown truncated and marked verified.
The leverage multiplier is on the card deliberately. A percentage without the leverage behind it is
not a claim anybody can evaluate, and a card that showed only the gain would be advertising rather
than a receipt.
### Reading a Position
A position card states the figures that decide the outcome: average fill, stop, last price,
unrealized profit and loss in absolute and percentage terms, trade value, market value, leverage, and
margin. A result means nothing without the leverage and margin beside it, which is why they sit on
the same card rather than behind a settings screen.
The middle card is the entry bar for that Bitcoin position, and it lands near the bottom of a lower
wick. The trade was the operator's own decision after reading market data and news, not a call the
agent made. What the system supplied was the thing that made a decision like that available at all:
the usual technical reads and the news that moves them, in one place, against the same live data the
transaction is then built from.
That is the argument for the whole design rather than for any single trade. Applying financial theory
to living market data is only useful if every action in the cycle, lending, staking, swaps, and
leverage, resolves in the same place for a person and for a bot. Doing that well produces a
specialized dataset as a byproduct, and the same reads have obvious applications beyond trading, in
onchain economies and GameFi systems that need to model markets rather than merely display them.
Serving that dataset quickly is one of the things the node program in the
[Litepaper](/litepaper/) exists to do.
## Reclaim a Stranded Order
A market order placed while its venue is closed sits with the keeper unfilled. If it never fills and
never auto-refunds, the collateral escrowed against it is stuck, and in most interfaces it is also
invisible: the backend that serves position data does not report pending orders at all, so the money
simply appears to be gone.
Ozmium reads pending orders straight from the Gains diamond contract rather than from any backend,
which is why a stranded order shows up here at all. Once the execute timeout has passed, **Reclaim**
cancels the order onchain and returns the escrowed collateral to your wallet. On a smart wallet the
call is batched so a gas-sponsored account can make it, which a raw write cannot.
Nothing about this is a favor Ozmium does for you. The cancel is a function on the venue's own
contract and the funds were always yours; the interface's contribution is showing you the order
exists and building the transaction that frees it.
## Pending Orders Are Not Positions
A resting limit or stop order holds collateral but is not an open position. They are listed
separately in the app and served by a separate endpoint. Treating them as the same thing is a classic
error in both human portfolio math and agent integrations.
### Underlying Protocols
{{protocols:gains}}
## FAQ
{{direct}}
### How does leverage work on Ozmium?
Leverage is provided by [Gains Network](https://gains.trade) gTrade using USDC as collateral. You post margin and open a
long or short perpetual on a supported market; position size equals margin times leverage. Ozmium
builds the transaction and your own wallet signs it.
### What is the maximum leverage on Ozmium?
Up to 200x, depending on the market. Each gTrade pair has its own maximum leverage and spread,
readable at `GET /v1/risk/pairs`. Maximum available is not a recommendation - at 200x a 0.5 percent
move liquidates the position.
### How is the liquidation price calculated?
Gains liquidates when a position's margin can no longer cover its losses. Ozmium shows the
liquidation price before you sign, but that figure excludes rollover and borrow fees, which accrue
continuously and move the real liquidation point closer over time.
### What is Auto Leverage?
Auto Leverage derives a suggested multiplier from the market's realized volatility over a window you
choose, rather than from a round number you picked. It answers what size survives how far this market
has genuinely moved. It is a floor, not a guarantee - markets exceed their history routinely.
### Does a stop loss guarantee my exit price?
No. In a fast gap the fill can be worse than the stop, or the position can reach liquidation before
the stop executes. A stop tells the venue when to act. What it fills at is decided by the market.
### Can I change leverage without closing the position?
Yes. `modify` adjusts take profit, stop loss, or leverage on an open position. Decreasing leverage
requires a collateral top-up, and Ozmium prepends the USDC approve automatically.
### What markets can I trade with leverage?
Crypto, forex majors and crosses, energy including oil, gas and uranium, metals including gold,
silver, copper and miners, indices, and stocks - six asset classes through gTrade.
## For Agents
- `GET /v1/risk/pairs` - tradeable pairs with pairIndex, max leverage, and spread.
- `GET /v1/positions/{address}` - open positions with size, leverage, liquidation price, and PnL.
- `GET /v1/pending-orders/{address}` - resting orders that have not filled.
- `GET /v1/history/{address}` - closed-trade ledger with exit reason (TP, SL, LIQ).
- `GET /v1/stats/{address}` - win rate, profit factor, expectancy, best and worst.
- `POST /v1/tx/risk/open`, `/close`, `/modify` - position lifecycle calldata.
See [Endpoint Catalog](/agents/endpoints/).
## Related
- [Charts](/guides/charts/) - how to read the chart, its indicators, and what a BUY or SELL marker means
- [Loan](/guides/borrow/) - leverage with a different liquidation model
- [Troubleshooting](/guides/troubleshooting/)
- [Terms And Risk](/company/terms/) - read this before using leverage
---
# About Ozmium
> What is Ozmium? A free, non-custodial AiFi and DeFi terminal on Base - trade, earn, borrow, and leverage from a wallet only you control.
URL: https://docs.ozmium.org/start/what-is-ozmium/
Markdown: https://docs.ozmium.org/start/what-is-ozmium/index.md
Keywords: what is ozmium, aifi terminal, ozmium base app, non-custodial defi interface, trade accumulate leverage, ai agent defi
Updated: 2026-07-27
**Ozmium is an AiFi and DeFi terminal on Base mainnet, free and non-custodial.** The same
capabilities serve a person in the app and an autonomous agent over the agent API, which is what
the Ai in AiFi means here. It is an interface rather than a protocol: it reads public onchain state, assembles transactions, and hands them to your
wallet to sign.
That distinction is the entire product. There is no Ozmium account, no balance held on your behalf,
and no withdrawal to request. Your assets stay in your wallet from the moment you arrive until the
moment you leave, and the only thing that ever moves them is a transaction you signed. The collapses
that defined the last cycle - Celsius, FTX, BlockFi - were custodial failures: users had sent their
assets to a company and were left filing claims against its estate. That failure mode does not exist
here, because there is nothing to send.
Which is what self-custody was supposed to mean. Software you can use without trusting whoever
operates it, and walk away from without asking permission.
## What You Can Do with It
Four things, on four screens, built to compose. An asset held in a wallet does nothing. Supplied to a vault, it earns. Pledged as collateral, it
borrows - and that is the step most people skip. Borrowing against a position raises cash without
selling it, so you keep the asset and whatever it does next, rather than closing the position to
fund something else. The stablecoins that come out can margin a hedge, buy more of what you actually
wanted, or sit idle earning yield until you need them. Hold, earn, borrow against, redeploy: the
ordinary mechanics of balance-sheet leverage, running without an underwriter, a credit committee, or
a counterparty who can call the loan.
| Action | Venue | What the Screen Gives You |
|---|---|---|
| **Trade** | Coinbase CDP Trade API, [Permit2](https://docs.uniswap.org/contracts/permit2/overview) | Spot swaps across the Base pair universe. Expected output, route, price impact, minimum received, maximum slippage, and protocol fee are itemized before you sign |
| **Earn** | Morpho ERC-4626 vaults, [Aave v3](https://aave.com/docs), [Aerodrome](https://aerodrome.finance), [Uniswap v3](https://app.uniswap.org) | A vault list carrying live net APY, TVL, and a 52-week APY range, with the vault contract address shown. Supply and withdraw are each one action. Providing liquidity to the OZ pools lives here too, and accrued swap fees can be collected without withdrawing the position |
| **Borrow** | [Morpho Blue](https://docs.morpho.org), [Morpho Midnight](https://docs.morpho.org) | Floating-rate collateralized loans against a visible LLTV ceiling, or fixed-rate fixed-term borrowing with a stated maturity. A risk panel reads the live position and reports how far the market must move to liquidate it |
| **Leverage** | [Gains Network gTrade](https://gains.trade) | Long or short perpetuals on USDC collateral, up to 200x, across six asset classes: crypto, forex, metals, energy, indices, and equities. Take-profit, stop-loss, and leverage are adjustable without closing |
## Design Principles
**One surface, many protocols.** Yield, borrowing, perpetuals, and swaps normally live in
separate apps with separate mental models. Ozmium puts them behind one portfolio view, so the
question "what should I do with this position" has one place to be answered.
**Sized against what the market has actually done.** Rather than offering you a leverage slider and
wishing you luck, the tooling reads the market's recent realized volatility and works backward to a
size that survives it. You see the liquidation price before you sign, not after, and you see how far
the market would have to move to reach it.
**Valuations are confidence-gated.** Where a price feed or RPC call fails, the interface retains the
last known-good value and marks it as stale rather than substituting zero. Unavailable data is
displayed as unavailable.
**AI agents are first-class.** Every capability in the app is also an HTTP endpoint an autonomous
agent can pay for per call. See [For AI Agents](/agents/overview/).
## Why This One
Anyone can generate an interface now. What does not fall out of a prompt is the part that has to be
correct: an encoding against a live contract, a number that stays honest when the feed behind it
fails, a stranded order somebody can actually recover. Those come from operating the thing, and
Ozmium's differences are all in that category.
**One surface across protocols that do not agree with each other.** Morpho, Aave, Gains, Aerodrome,
and Uniswap each scale parameters differently, use different decimals, and mean different things by
the same word. Reconciling them into one portfolio view and one set of correctly encoded transactions
is the work, and it does not generalize from a template.
**The same terminal for people and for AI agents.** Every capability in the app is an HTTP endpoint an
agent pays for per call, priced from a tenth of a cent, with no account, no key, and no SDK. Payment
is the credential. Most products bolt an API onto a UI; here they are the same surface, which is what
AiFi means when it is not a slogan.
**Failure states that tell the truth.** A dead price feed holds its last known-good value and marks
it stale rather than printing a confident zero. An agent's factual claim is blocked unless a tool
call backs it. A market order the venue never filled is surfaced and recoverable rather than silently
absorbed. Each of those is a decision made after watching the alternative hurt someone.
**Built where the industry does not build.** The operation runs from rural America, in service of
small independent builders rather than institutional flow, and the aim is to put this infrastructure
somewhere physical rather than only onchain. That constrains what gets built: tools people can afford
to use, priced for a person putting in a hundred dollars rather than a fund putting in a million.
## Built for Its Own Operator
Ozmium is used daily by the person who builds it, and the specialization shows. The reason every
technical read and the news that moves it sit on one screen, and the reason lending, staking, swaps,
and leverage all resolve in the same place rather than across five tabs, is that this is the tool its
author wanted and could not find.
That is worth stating rather than dressing up as market research. Software built for a real user with
a real position tends to be honest about the parts that hurt, because the author is the first person
the dishonest version would cost.
## Custody
"Non-custodial" gets used loosely enough that it is worth spelling out mechanically. So what does it
actually mean here?
1. Ozmium operates no contract that holds user funds.
2. Every write action resolves to a standard Base transaction `{ to, data, value }`.
3. Your wallet shows you that transaction, and you approve it or you do not.
4. If Ozmium disappeared tomorrow, every position you hold is still yours and still manageable
directly at Morpho, Aave, Gains, Aerodrome, or Uniswap.
## FAQ
{{direct}}
### Is Ozmium custodial?
No. Ozmium operates no contract that holds user funds and never signs on your behalf. Every action is
a standard Base transaction your own wallet approves, and every position remains manageable directly
at the underlying protocol if Ozmium disappeared.
### What protocols does Ozmium use?
[Gains Network](https://gains.trade) [gTrade](https://gains.trade) for leveraged perpetuals with USDC collateral, Morpho and Aave v3 for lending
vaults and collateralized borrowing, Uniswap v3 and Aerodrome for the OZ liquidity pools, and the
[Coinbase Developer Platform](https://www.coinbase.com/developer-platform) for swap routing and on-ramps.
### Why is Ozmium only on Base?
Base is an Ethereum layer-2 built and incubated by Coinbase, secured by Ethereum, and operated as
public infrastructure with a stated commitment to open-source development and progressive
decentralization. Building on Ethereum means inheriting the most battle-tested settlement layer in
the industry; building on Base means inheriting that security at fees low enough that modest
positions and active management are economically sensible.
Deploying to a single network is also a correctness decision. One chain means one verifiable
contract address set, one gas model, and no bridge dependency introduced by this interface. Bridges
have historically been the largest single category of loss in this sector, and Ozmium does not
operate or route through one.
### Can I use Ozmium without a wallet?
You can browse it without one. Public data - vault lists with live APY, the tradeable pair universe,
charts, and loan markets - renders clean and fully usable in preview mode. Wallet-keyed views are
covered with frosted glass over clearly labeled demo samples, and nothing throws a connect popup at
you. Transacting is what needs a wallet.
### Does Ozmium charge fees?
Not to humans. The app is free, and Ozmium takes no cut of swaps. You still pay network gas, the
underlying venue's own fees, and price impact. Automated clients pay per call for the agent API.
### Does Ozmium send me tax forms or account statements?
No. Ozmium is not a broker, issues no statements or forms, and reports nothing to any tax authority
on your behalf. Your records are the chain itself: every transaction under your address is
permanently readable on free block explorers such as [Basescan](https://basescan.org), which will
export a complete history. Whether a given trade, yield payment, or liquidation creates a taxable
gain or a deductible loss depends on your jurisdiction and your situation, and that is a question for
a qualified professional. See [Terms And Risk](/company/terms/#records-and-tax).
### Is Ozmium a bank or a broker?
No. Ozmium is not a bank, broker, dealer, exchange, adviser, or your counterparty, and it does not
solicit or recommend transactions. It is software that builds transactions you choose to sign.
## Where to Go Next
- The whole thesis in one document: [Litepaper](/litepaper/)
- New to all of this: [Quickstart](/start/quickstart/)
- The Ozmium agent: [Ozwald](/ozwald/overview/)
- Need a wallet or a Base account: [Wallets And Base](/start/wallets-and-base/)
- Unfamiliar terms: [Glossary](/company/glossary/)
- Building an agent: [For AI Agents](/agents/overview/)
---
# Endpoint Catalog
> Every Ozmium /v1 endpoint with its USDC price and purpose - data reads, alpha, transaction builders for swaps, vaults, loans and perps, prop desk, and referrals.
URL: https://docs.ozmium.org/agents/endpoints/
Markdown: https://docs.ozmium.org/agents/endpoints/index.md
Keywords: ozmium api endpoints, v1 endpoint catalog, crypto price api usdc, transaction builder api, base mainnet calldata api
Updated: 2026-07-27
Base URL: `https://ozmium.org/v1`
:::note The live catalog is authoritative
The catalog at [`/v1`](https://ozmium.org/v1) is free, complete, and generated from the running
service. This page is the readable version. If the two ever disagree, the live catalog wins.
:::
## Data Endpoints - $0.001 per Call
| Endpoint | Returns |
|---|---|
| `GET /v1/prices?symbols=BTC,ETH` | Two labeled venues per symbol: Coinbase exchange spot with 24h stats, and the [gTrade](https://gains.trade) leg `{ gains: { pairIndex, mark, index } }`. `mark` is what fills on Gains; `index` is the oracle spot liquidations use. The cross-venue spread is real, tradeable divergence. Covers Gains-listed symbols Coinbase does not carry. |
| `GET /v1/crowd?symbols=BTC,ETH` | Live gTrade crowd positioning: long vs short split in percent and USD, both sides, total book, plus `bookSharePct` - each pair's share of the whole Gains open book. 90 percent long on a pair holding 4 percent of the venue's money is a very different signal than 90 percent long on a rounding error. |
| `GET /v1/signals?symbols=ETH,BTC` | Multi-indicator TA bundle - RSI, MACD, Bollinger, VWAP, trend, candlestick pattern - reduced to a directional bias and a conviction score. |
| `GET /v1/candles?product=ETH-USD&days=30` | OHLCV series. |
| `GET /v1/swap/price` | Expected output, route, and fees. |
| `GET /v1/portfolio/{address}` | Token balances with confidence-gated USD valuation. Never a fabricated zero. |
| `GET /v1/positions/{address}` | Open leveraged perp positions: size, leverage, liquidation price, PnL. |
| `GET /v1/pending-orders/{address}` | Resting limit and stop orders that have **not** filled. These hold collateral but are not positions. |
| `GET /v1/history/{address}` | Closed-trade ledger with entry, exit, and reason: TP, SL, or LIQ. |
| `GET /v1/stats/{address}` | Trading scorecard: trades, win rate, net USD, gross profit and loss, profit factor, mean R-multiple expectancy, average win and loss, best and worst. The natural input to a risk-sizing agent. |
| `GET /v1/earn/vaults` | Morpho and Aave vault list with live APY. |
| `GET /v1/loan/markets` | Floating-rate collateral markets with LLTV, borrow APY, and liquidity. |
| `GET /v1/loan/fixed` | Every live [Morpho Midnight](https://docs.morpho.org) fixed-rate, fixed-term book: marketId, tokens, LLTV, oracle, maturity, and both sides' implied APRs (borrow is best bid, lend is best ask). |
| `GET /v1/risk/pairs` | Tradeable Gains gTrade pairs with pairIndex, max leverage, and spread. |
| `GET /v1/ideas/asset/{sym}` | Does one named market have a worthwhile leverage edge right now, and what would be better instead or as a hedge? Direction, range-survival leverage, entry, stop, target, liquidation, edge. |
## Alpha Endpoints
| Endpoint | Price | Returns |
|---|---|---|
| `GET /v1/ta/{sym}?gran=900` | $0.005 | The complete chart read for one symbol at your timeframe (1m, 5m, 15m, 1H, 1D) - everything the Ozmium chart shows a human, as data. |
| `GET /v1/ideas/compare?a=ETH&b=BTC` | $0.005 | Relative-strength / pairs-trade read. When one leg sits near the top of its recent range and the other near its bottom, the spread is stretched and mean reversion favors long-the-laggard, short-the-leader. Plus each leg's own edge. |
| `POST /v1/prop/quote` | $0.005 | What the prop desk would charge for a given action, and whether the paying wallet qualifies. |
| `GET /v1/ideas?worthwhileness=strict` | $0.008 | The strict shortlist: only the highest-conviction setups sitting on a 52-week extreme, one per direction per category. |
| `GET /v1/ideas?limit=6` | $0.01 | Ranked long and short leverage setups across every category - crypto, forex, energy, metals, indices, stocks. About a year of daily candles reduced to a composite technical signal, ranked by edge times leveraged profit per unit time. Each executable via `/v1/tx/risk/open`. |
| `GET /v1/arbitrage?target=cbBTC&budget=100&taker=0x..` | $0.01 | Ranked, **fee-netted** cross-asset and DEX-versus-Coinbase arbitrage routes into the target. Each executable via `/v1/tx/swap`. |
| `GET /v1/ta/scan?symbols=BTC,ETH,SOL` | $0.01 | Cross-asset buy/sell dominance in one call for up to eight symbols across 1m, 5m, and 15m. |
| `GET /v1/loan/analysis/{address}` | $0.01 | Borrow-position risk analysis. |
| `GET /v1/ideas/summary` | $0.01 | Market-wide edge aggregate: single best long and best short across all markets, top long and short per category, and breadth counts. |
| `GET /v1/ideas?worthwhileness=loose&limit=16` | $0.01 | The fuller field including marginal plays, for coverage or hedge scanning. |
| `GET /v1/alpha` | $0.01 | The whole alpha stack in one call - arbitrage routes, ranked ideas, and the TA bundle. Cheaper and faster than polling the three separately. |
## Transaction Builders - $0.01 per Call
Every builder returns ready-to-sign `{ to, data, value }` encoded for Base mainnet. You broadcast from
your own wallet. Ozmium never signs.
**Basics**
- `POST /v1/tx/swap` - spot swap on Base (CDP Trade API plus [Permit2](https://docs.uniswap.org/contracts/permit2/overview)).
- `POST /v1/tx/send` - transfer a token or ETH.
- `POST /v1/tx/tip` - fund the Ozmium prop desk. No return promised.
- `POST /v1/tx/burn` - burn OZ to the dead address and rank on the onchain burn ladder.
**Earn**
- `POST /v1/tx/earn/deposit`, `/v1/tx/earn/withdraw` - ERC-4626 Morpho vault supply and redeem.
- `POST /v1/tx/earn/aave/supply`, `/v1/tx/earn/aave/withdraw` - Aave supply and withdraw.
**Borrow**
- `POST /v1/tx/loan/supply-collateral`, `/borrow`, `/repay`, `/withdraw-collateral` - the [Morpho Blue](https://docs.morpho.org)
floating-rate lifecycle.
- `POST /v1/tx/fixed/supply-collateral`, `/borrow`, `/repay`, `/withdraw-collateral` - Morpho Midnight
fixed rate. The borrow builder quotes the live bid book for your target and encodes the takes in
order, clamped by a slippage-guarded worst price. The rate locks at execution to the market
maturity.
**Leverage**
- `POST /v1/tx/risk/open`, `/v1/tx/risk/close`, `/v1/tx/risk/modify` - Gains gTrade perps with USDC
collateral, up to 200x, with exact scaling handled for you: leverage x1e3, prices x1e10, USDC 6dp,
slippage x1e3. `modify` takes `action: tp | sl | leverage` and adjusts an open position **without
closing it**. A leverage decrease auto-prepends the USDC approve for the collateral top-up.
**Liquidity**
- `POST /v1/tx/lp/aero/add`, `/v1/tx/lp/aero/remove` - [Aerodrome](https://aerodrome.finance) vAMM OZ/USDC, with ERC-20 approves
for both sides prepended when the live allowance is short.
- `POST /v1/tx/lp/uni/add`, `/v1/tx/lp/uni/remove` - [Uniswap v3](https://app.uniswap.org) OZ/WETH 1 percent pool at **full
range**, bundled multicall, ETH auto-wrapped and excess refunded. On remove, `liquidity: 0`
**collects fees only** - that is the claim path.
## Prop Desk
| Endpoint | Price | Notes |
|---|---|---|
| `POST /v1/prop/quote` | $0.005 | OZ cost, match factor, and eligibility. Needs `actionId` plus that action's parameters. |
| `POST /v1/prop/execute` | $0.01 | Runs the action. Needs `actionId`, parameters, and `payTxHash` (agents) or `burnTxHash` (humans). |
The x402 fee does **not** authorize a prop action. See [Prop](/guides/prop-desk/).
## Free
| Endpoint | Returns |
|---|---|
| `GET /v1` | The full catalog and live prices |
| `GET /v1/referrals/{wallet}` | Your referral tally and amount owed |
| `GET /v1/oz-credit/{wallet}` | Your prepaid OZ credit balance and the rail's full terms |
## Paying Half
Every price on this page is the USDC price. Prepaid OZ credit covers the same calls at **half** of it
and is exempt from congestion surge. See [the credit rail](/agents/x402/#paying-in-oz-the-credit-rail).
## Related
- [x402 Payments](/agents/x402/)
- [Integration Notes](/agents/integration/)
- [Agent API Overview](/agents/overview/)
---
# Engine
> The AI NPC game engine Ozmium is building - autonomous characters deciding outside the renderer on local models, plus dialogue, voice, and character generation.
URL: https://docs.ozmium.org/also/labs/
Markdown: https://docs.ozmium.org/also/labs/index.md
Keywords: ai npc game engine, local llm npc behavior, unreal engine ai agents, jrpg voice generator, autonomous character ai
Updated: 2026-07-28
Ozmium is building a game engine. Not a game yet, and not a product on any schedule, but the
components a game would need: characters that decide for themselves, a dialogue system that can voice
a full cast, and a pipeline that generates the characters in the first place.
Everything here runs on hardware Ozmium owns, on local models, at power draws measured in watts. That
constraint is the point rather than a limitation, and it is the same one the rest of Ozmium is built
under.
## Characters That Decide
{{video-wide:ozmium-npc-companions-unreal|A party of AI NPCs crossing a test town in Unreal Engine.}}
{{video-wide:ozmium-npc-turns-back|One companion falls behind. A second notices and turns back. A third does not.}}
A group travels together through a test town. One falls behind. Another registers it and turns around
to help. The third registers it too and keeps walking.
None of those three responses is scripted, and the divergence is the entire result. A scripted party
is unanimous, because unanimity is what scripts produce. The companion who keeps walking is running
the same stack as the one who turns back, with the same information available, and they disagree
because they are different characters weighing the same event.
**Each character is a separate process.** The engine renders; the decision layer for each host runs
outside it as its own local service, holding that character's state and choosing its actions. Unreal
polls each brain over a local HTTP loop at 10Hz and applies the returned position and heading to the
character it owns. What appears in the viewport is the engine animating decisions made somewhere
else, per character, independently. Three hosts means three brains disagreeing in real time.
The decision layer sits on a **14B language model running locally**, drawing less power than a games
console, with no cloud inference, no per-token bill, and no rate limit. The design premise is that an
agent should act under acknowledged uncertainty rather than stall until it has a guaranteed correct
answer, which is a literal description of what a language model does at inference time anyway.
## Dialogue and Voice
{{video-wide:ozmium-jrpg-vox-generator|Building a full dialogue script with sampled character voices.}}
Anyone who played a Camelot Software Planning game knows the sound: NPC speech rendered as pitched
tonal blips rather than recorded voice, one voice per character, expressive without a single line of
recorded audio.
This tool generates that system. It samples custom sounds, assigns a voice per character, and builds
dialogue scripts across an entire game rather than one line at a time. Characters who decide for
themselves need lines nobody wrote in advance, so a generative voice layer is a requirement here
rather than a convenience.
## Character Generation
{{video-wide:ozmium-ai-mascot-creation|Generating a character end to end.}}
Character creation, run locally, end to end. A world populated by autonomous characters needs more of
them than any artist would hand-build, and the same pipeline that produces game characters produces
brand ones.
## Where This Goes
An **ORPG** is the eventual target: autonomous characters who travel, notice, and decide, in a world
whose economy can settle onchain on infrastructure that already works.
It is unannounced, undated, and last in priority behind every product on this site. It appears here
because the engine underneath it is real and running, and because the same discipline that produced
it produced the trading interface.
## Related
- [Ozwald](/ozwald/overview/)
- [Bard: The Theremini App](/also/bard/)
- [Andhakara](/also/andhakara/)
---
# Charts
> How to read the Ozmium chart on the Risk screen - candles, timeframes, indicator chips, candlestick patterns, and what a BUY or SELL marker actually means.
URL: https://docs.ozmium.org/guides/charts/
Markdown: https://docs.ozmium.org/guides/charts/index.md
Keywords: how to read candlestick chart, crypto chart indicators explained, rsi macd cvd explained, buy sell signal meaning, ozmium risk chart
Updated: 2026-07-28
The chart on the **Risk** screen is the same one that sizes a position, so what it shows and what the
ticket does are never two different opinions. This page explains how to read it.
:::warning The markers are experimental
Every signal, marker, and score described below is **unproven**. There is no established
out-of-sample edge, none of it is financial advice, and the app labels it as experimental on the
chart itself. Read it as one input among several.
:::
## Picking a Market
The market picker opens a searchable list of every tradeable pair. Tabs narrow it by class - crypto,
forex, metals, energy, indices, equities - and the **star tab is your favorites**.
Tapping the star on any row favorites that market. The star swallows the tap so it never opens the
market by accident, and favorites are stored per device rather than against your wallet, so nothing
about your list touches the chain or leaves the browser.
## Candles and Timeframes
Two controls change what you see, and they are independent of each other.
| Control | What It Sets |
|---|---|
| Candle Size | How much time one bar covers: 1m, 5m, 15m, 1H, 4H, 6H, 1D, 1W, 1M, 1Y. |
| Range | How much total time is on screen, from three minutes out to the market's entire life. |
Because they are separate, one-minute candles across a full day and daily candles across a year are
both valid views. Your choice is remembered per market, so returning to a pair reopens it the way you
left it.
A candle size is offered only when the market has actually existed long enough to draw one. A pair a
few months old will not offer yearly bars, because three bars is the minimum that can be read as a
chart at all.
Zoom far enough out and the chart switches from candles to a line. Past roughly four hundred visible
bars the candles overlap into noise, so the line is the honest rendering.
Switching timeframe keeps the old bars on screen while the new ones load. You never get a blank
chart, and the previous view stays readable until the replacement is ready.
## Reading a Candle
Each candle covers one interval and reports four numbers: where the interval opened, where it closed,
and the highest and lowest it traded. The body spans open to close, green when the close was higher
and red when it was lower. The thin wicks above and below reach to the high and the low.
A long body means one side controlled the whole interval. A small body with long wicks means price
went somewhere and came back, which is a different market than the one that simply went up.
## Candlestick Patterns
Specific shapes and sequences have names, and the chart marks them when they appear. Tapping any
marked formation opens its clinical definition alongside a citation, so you can read the textbook
source rather than take the app's word for it.
| Pattern | What It Describes |
|---|---|
| [Bullish Engulfing](https://www.investopedia.com/terms/b/bullishengulfingpattern.asp) | A small red candle fully engulfed by the next, larger green one. Buyers overwhelm the prior session after a decline. |
| [Bearish Engulfing](https://www.investopedia.com/terms/b/bearishengulfingpattern.asp) | A small green candle fully engulfed by the next, larger red one. Sellers overwhelm the prior session after an advance. |
| [Hammer](https://www.investopedia.com/terms/h/hammer.asp) | A small body at the top with a long lower shadow after a downtrend. Sellers pushed price down and buyers reclaimed it. |
| [Hanging Man](https://www.investopedia.com/terms/h/hangingman.asp) | The same shape after an uptrend, where the long lower shadow instead warns that selling is appearing. |
| [Shooting Star](https://www.investopedia.com/terms/s/shootingstar.asp) | A small body at the bottom with a long upper shadow after a rally. Buyers drove price up and were rejected. |
| [Doji](https://www.investopedia.com/terms/d/doji.asp) | Open and close virtually equal, forming a cross. Neither side won the session. |
| [Morning Star](https://www.investopedia.com/terms/m/morningstar.asp) | A three-bar bottoming reversal: large red, a small-bodied pause, then a large green closing back into the first. |
| [Evening Star](https://www.investopedia.com/terms/e/eveningstar.asp) | The topping equivalent: large green, a pause, then a large red closing back into the first. |
| [Three White Soldiers](https://www.investopedia.com/terms/t/three_white_soldiers.asp) | Three consecutive long green candles, each closing higher. Sustained buying. |
| [Three Black Crows](https://www.investopedia.com/terms/t/three_black_crows.asp) | Three consecutive long red candles, each closing lower. Sustained selling. |
| [Piercing Pattern](https://www.investopedia.com/terms/p/piercingpattern.asp) | A red candle, then a green one opening below the low and closing above the red body's midpoint. |
| [Dark Cloud Cover](https://www.investopedia.com/terms/d/darkcloud.asp) | A green candle, then a red one opening above the high and closing below the green body's midpoint. |
| [Marubozu](https://www.investopedia.com/terms/c/candlestick.asp) | A long body with no meaningful shadows. One side controlled the entire session, open to close. |
## The Indicator Chips
Underneath the price, the indicator pane draws several measurements on a shared scale, and each one
appears as a tappable chip. Tapping a chip opens its definition and citation, the same way a pattern
does.
| Chip | What It Measures |
|---|---|
| [Trend](https://www.investopedia.com/terms/t/trendanalysis.asp) | Direction and persistence of the move. |
| [RSI](https://www.investopedia.com/terms/r/rsi.asp) | Momentum on a 0 to 100 scale. Conventionally, above 70 reads as overbought and below 30 as oversold. |
| [MACD](https://www.investopedia.com/terms/m/macd.asp) | The relationship between two moving averages, used to spot momentum shifts. |
| [Stochastic Oscillator](https://www.investopedia.com/terms/s/stochasticoscillator.asp) | Where the close sits within its recent high-low range. |
| [Williams %R](https://www.investopedia.com/terms/w/williamsr.asp) | A related momentum reading on an inverted scale. |
| [Moving Average](https://www.investopedia.com/terms/m/movingaverage.asp) | The average close over a window, here twenty bars. |
| [Bollinger Bands](https://www.investopedia.com/terms/b/bollingerbands.asp) | Bands set a number of standard deviations from that average, so width is volatility. |
| [Rate Of Change](https://www.investopedia.com/terms/p/pricerateofchange.asp) | How fast price has moved over a window, regardless of direction. |
| [ADX](https://www.investopedia.com/terms/a/adx.asp) | How strong a trend is, without saying which way it points. |
| [OBV](https://www.investopedia.com/terms/o/onbalancevolume.asp) | Running volume weighted by whether each bar closed up or down. |
| [CVD](https://www.investopedia.com/terms/v/volume.asp) | Cumulative volume delta, the running difference between buying and selling pressure. |
| [Open Interest](https://www.investopedia.com/terms/o/openinterest.asp) | How much leveraged position is currently open in this market. |
A [divergence](https://www.investopedia.com/terms/d/divergence.asp) is when price and an indicator
disagree - price making a new high while momentum does not, for instance - and both the pane and the
markers treat that as meaningful.
## What BUY and SELL Mean
A marker on a bar is a **directional read**, and the two words map directly onto the two things you
can do with a perpetual:
| Marker | Direction | The Position It Suggests |
|---|---|---|
| **BUY** | Long | You profit if price rises, and are liquidated if it falls far enough. |
| **SELL** | Short | You profit if price falls, and are liquidated if it rises far enough. |
**SELL does not mean sell what you own.** On the Risk screen it means open a short, which is a new
position rather than an exit. Closing an existing position is a separate action.
Each marker carries a **conviction** value rather than being a yes or no. That number comes from
combining every indicator above into one weighted read, where each input leans bullish or bearish and
carries its own weight. Agreement across many inputs produces high conviction; a single indicator
firing alone produces low conviction, and the marker is drawn faintly to say so.
Several conditions deliberately suppress a marker or force it to neutral:
- **Regime gating.** A long signal in a market whose broader trend is down is downgraded rather than
shown, because the setup and the environment contradict each other.
- **Macro blackout.** Around scheduled high-impact events, directional reads are withheld.
- **Thin books.** Crowd positioning is only read as a signal when there is enough open interest to
mean anything, and never gets to outvote the measured indicators.
The last constraint is worth stating plainly: **crowd positioning is capped at half the influence of
the measured signal**, because it is the one input that cannot be backtested. Gains publishes no
positioning history, so a live book read against an old bar would be an anachronism.
### What They Look Like in Practice
Four consecutive BUY markers on silver, each landing at a local low before the move. The liquidation
line for the open position is drawn above the price, and the indicator pane carries RSI, MACD, and
CVD across the same window.
One chart is not evidence of an edge, and this page has already said the markers are unproven. It is
shown because it is what a working signal looks like when it works, and because reading the markers
against the pane beneath them is the skill this page is trying to teach.
## Where the Data Comes From
None of this is invented, and none of it is a single feed taken on faith.
| Layer | Source |
|---|---|
| Onchain State | Base mainnet, read directly over JSON-RPC. Balances, positions, pool state, and pending orders come from the contracts themselves rather than from an intermediary. |
| Perpetual Markets | [Gains Network gTrade](https://gains.trade), for pair parameters, open interest, and the live book. |
| Lending Markets | Morpho and Aave, for vault and market state. |
| Spot Prices and Routes | [Coinbase Developer Platform](https://www.coinbase.com/developer-platform), alongside [Coinbase Advanced Trade](https://www.coinbase.com/advanced-trade) market data. |
| Equities, Indices, Forex, and Commodities | Public market data feeds covering the non-crypto classes [gTrade](https://gains.trade) lists. |
| Reference and Corroboration | Public aggregators, used to cross-check rather than as a primary. |
Two rules govern how those are combined. **A figure is never reported more confidently than its
source supports**, so a failed read holds its last known-good value and marks it stale instead of
printing a zero. And **no single feed is trusted alone** where a second one exists to check it, which
is why a price that two sources disagree about is treated as uncertain rather than averaged into
false precision.
The specific weighting, cross-checking, and signal construction are not published.
## The Backtest Panel
The signal panel can replay the strategy over the loaded window, recomputing the verdict at each bar
from only the information available at that bar and checking how often the direction matched the next
candle. That produces a win rate over the tested window.
Treat it as a description of that window and nothing more. It is not a forecast, the sample is small,
and a strategy that fit one window is not thereby correct about the next.
## Related
- [Risk](/guides/leverage/)
- [Trade](/guides/trade/)
- [Terms And Risk](/company/terms/)
---
# Install as an App
> Pin Ozmium to your home screen on iPhone or Android, add it to the Base App, or open it as a Farcaster mini-app. No app store required.
URL: https://docs.ozmium.org/start/web-apps/
Markdown: https://docs.ozmium.org/start/web-apps/index.md
Keywords: install ozmium app, add to home screen pwa, base app pinned apps, farcaster mini app, progressive web app crypto
Updated: 2026-07-28
Ozmium is a progressive web app. There is nothing in an app store, nothing to download, and no
review process between a change being shipped and you having it. Adding it to your device takes a few
taps and produces an icon that behaves like any other app: its own window, no browser chrome, and its
own place on your home screen.
Four hosts are supported, and all of them run the same site.
## iPhone and iPad
Safari is required for this. Chrome and Firefox on iOS can open Ozmium perfectly well, but only
Safari can write to the home screen.
1. Open [ozmium.org](https://ozmium.org) in **Safari**.
2. Tap the **Share** button in the toolbar, the square with an arrow pointing up.
3. Scroll down the share sheet and tap **Add to Home Screen**.
4. Confirm the name, leave **Open as Web App** enabled, and tap **Add**.
The icon lands on your home screen. Opening it launches Ozmium full-screen without the address bar,
and it keeps its own session, so a connected wallet stays connected between launches.
If you do not see **Add to Home Screen**, you are in a browser other than Safari, or the option is
below the visible area of the sheet. Scroll further.
## Android
Chrome usually offers this on its own. If it has not:
1. Open [ozmium.org](https://ozmium.org) in **Chrome**.
2. Tap the **three-dot menu** in the top right.
3. Tap **Add to Home screen**, or **Install app** if Chrome offers that instead.
4. Confirm.
Samsung Internet, Edge, and Firefox on Android all support the same thing under similar wording.
## Desktop
Chrome and Edge both install web apps on Windows, macOS, and Linux. Look for the **install icon** in
the address bar, a small monitor with a downward arrow, or open the browser menu and choose
**Install Ozmium** or **Apps, Install this site as an app**.
The result is a standalone window with its own taskbar or dock entry.
## The Base App
Inside the [Base App](https://base.app/invite/ozbeta/D1H4FT25), Ozmium opens as a mini-app with the
host wallet already connected, so there is no separate connection step.
1. Open the Base App and go to its **browser**.
2. Enter **ozmium.org** in the address field.
3. Once Ozmium loads, open the **three-dot menu** in the browser bar and choose **Pin**. The same
menu manages notifications for the pinned app.
Base publishes no end-user guide for its browser or for pinning apps, so the steps above are
described from the app itself rather than cited. [docs.base.org](https://docs.base.org) is developer
documentation, and its [mini-apps section](https://docs.base.org/mini-apps) covers how a mini-app is
built rather than how you pin one. If the Base App changes its controls, trust the app over this
page.
## Farcaster
Ozmium is also a [Farcaster](https://farcaster.xyz/~/code/1914H5) mini-app. Opened from a cast or from the mini-app directory, the wallet
your Farcaster client already holds is the wallet Ozmium uses.
1. Open your Farcaster client.
2. Find Ozmium through the **mini-apps directory**, or open any cast linking to it.
3. Add it to your own mini-apps list using the client's add control.
[miniapps.farcaster.xyz](https://miniapps.farcaster.xyz) is likewise developer documentation. It
describes how clients handle mini-apps, not how you add one, and the add control differs between
Farcaster clients.
New to Farcaster? Our invite is at
[farcaster.xyz](https://farcaster.xyz/~/code/1914H5).
## What Installing Changes
| | Installed | In a Browser Tab |
|---|---|---|
| Launch | Home Screen Icon, Own Window | Address Bar and Tabs |
| Session | Persists between Launches | Persists, Subject to Browser Cleanup |
| Updates | Automatic on Next Launch | Automatic on Reload |
| Custody | Unchanged. Your Wallet, Your Keys | Unchanged |
Installing changes presentation and nothing else. There is no separate build, no additional
permission, and no extra access to your device. It is the same site, in its own window.
## Related
- [Quickstart](/start/quickstart/)
- [Wallets And Base](/start/wallets-and-base/)
- [Troubleshooting](/guides/troubleshooting/)
---
# Integration Notes
> The mistakes AI agents actually make wiring up Ozmium - pending orders versus positions, parameter scaling, prepended approvals, and safe unsupervised defaults.
URL: https://docs.ozmium.org/agents/integration/
Markdown: https://docs.ozmium.org/agents/integration/index.md
Keywords: ai agent onchain integration, agent trading safeguards, unsupervised execution defaults, prepended erc-20 approve, agent retry idempotency
Updated: 2026-07-27
This page is the accumulated list of things that go wrong. Read it before you write the integration,
not after.
## Pending Orders Are Not Positions
`GET /v1/positions/{address}` returns open positions. `GET /v1/pending-orders/{address}` returns
resting limit and stop orders that have **not** filled.
Pending orders hold collateral but carry no market exposure. An agent that sums both into "current
exposure" will over-report risk and refuse trades it should take. An agent that ignores pending
orders entirely will over-commit collateral it does not have.
Query both. Treat them separately.
## Do Not Modify the Calldata
Transaction builders return `{ to, data, value }` encoded for the exact contracts, parameter scales,
decimals, and market ids on Base mainnet. That encoding is the product.
If you re-encode, round, or "fix" any field, you own the result. The most common self-inflicted
reverts come from an agent adjusting a value it did not need to touch.
## Scaling Is Already Done
Gains [gTrade](https://gains.trade) uses leverage at 1e3, prices at 1e10, USDC at 6 decimals, and slippage at 1e3. Morpho
Blue uses market ids and per-asset decimals. Aave uses its own. [Uniswap v3](https://app.uniswap.org) uses ticks.
The builders handle all of it. Send human-scale values in the request body; do not pre-scale them.
## Approvals
Where an approve is required and the live allowance is short, builders **prepend** it. That means:
- Some responses contain more than one transaction. Broadcast them in the order given.
- A leverage **decrease** requires a collateral top-up, so the USDC approve is prepended
automatically.
- LP adds prepend approves for both sides.
An agent that only broadcasts the first transaction in a multi-step response will approve and never
act, or act and never approve.
## Never Fabricate a Zero
`GET /v1/portfolio/{address}` returns confidence-gated USD valuation. When a valuation is not
confident, the endpoint says so rather than returning `0`.
:::danger Do not coerce uncertainty to zero
A wallet reported as worth $0 because a price feed blipped is how an agent liquidates a healthy
position or refuses a valid trade. Preserve the uncertainty in your own layer and handle it
explicitly.
:::
## Read the Price from the Challenge
Prices may surge during congestion. Do not hardcode the prices from the docs. Read the amount from
the 402 challenge on every call and sign that exact amount. See [x402 Payments](/agents/x402/).
## Payment Is Not Prop Authorization
The x402 fee buys the call. A prop desk action additionally requires a real onchain OZ transfer,
passed as `payTxHash` (agents) or `burnTxHash` (humans). Missing or invalid hashes are refused with
`bad payTxHash` or `bad burnTxHash`. See [Prop](/guides/prop-desk/).
## Safe Defaults for Unsupervised Execution
An agent that will not be watching should behave differently from one a human is supervising:
- **Full range on Uniswap v3.** A concentrated position that leaves its band stops earning and sits
fully converted into the losing side. Ozmium defaults to full range for exactly this reason. Do not
narrow it unless something is monitoring it.
- **Set TP and SL at open.** Not later. There may not be a later.
- **Size against what the market has done to this asset.** `GET /v1/ideas/asset/{sym}` returns a
range-survival leverage. Use it as a ceiling.
- **Budget the rollover.** Perpetual funding accrues continuously and moves the real liquidation
point closer on a position left alone. A position held for a week is not the same trade as the same
position held for an hour.
- **Cap total spend.** Both the USDC you pay in x402 fees and the capital you deploy. An
unbounded retry loop against a 402 is an expensive bug.
## Treat the Marker Feeds as Unproven
`/v1/ta` and `/v1/ta/scan` are experimental. There is no established out-of-sample edge, and none of
it is financial advice. If your agent acts on them, it should treat them as one input among several,
not as a trigger.
## Idempotency and Retries
There is no idempotency key. A retried transaction builder call costs another $0.01 and returns fresh
calldata against fresh market state, which is the correct behavior - stale calldata is a good deal
worse than a second penny.
Retry the **build**. Never the broadcast. Do not rebroadcast a transaction you are not certain failed;
check the chain first.
## Rate Limits
Anonymous traffic has a low ceiling. Paid traffic is granted a far higher one automatically, keyed to
the paying wallet. If you are rate limited while paying, you are probably retrying unpaid requests in
a loop rather than sending the payment header.
## Discovery for Frameworks
- MCP tool manifest: `https://ozmium.org/v1/tools.json`
- MCP server card: `https://ozmium.org/.well-known/mcp/server-card.json`
- OpenAPI 3.1 with `x-payment` pricing: `https://ozmium.org/v1/openapi.json`
- Agent skills index: `https://ozmium.org/.well-known/agent-skills/index.json`
## Related
- [Endpoint Catalog](/agents/endpoints/)
- [x402 Payments](/agents/x402/)
- [Troubleshooting](/guides/troubleshooting/)
---
# Earn
> Supply assets to Morpho and Aave v3 vaults through Ozmium - where the yield actually comes from, how to read APY honestly, and the risks worth naming.
URL: https://docs.ozmium.org/guides/earn/
Markdown: https://docs.ozmium.org/guides/earn/index.md
Keywords: earn yield on base, morpho vaults base, aave v3 supply apy, erc-4626 vault deposit, defi lending risk
Updated: 2026-07-27
Earning means supplying an asset to a lending market and collecting the interest borrowers pay. The
yield is not manufactured by Ozmium; it comes from real borrowers paying real rates.
## Where the Yield Comes From
Someone is borrowing your asset and posting collateral worth more than they borrowed. They pay
interest. That interest, minus the protocol's share, is your yield.
This matters because it sets the ceiling. If a vault advertises a rate far above what borrowers
plausibly pay, the extra is coming from somewhere else - token emissions, a subsidy, or a risk you
have not priced. Ask which.
## Supported Venues
| Venue | Model | What Ozmium Shows |
|---|---|---|
| Morpho | ERC-4626 Vaults, Curated | Every listed vault with live APY, not just ones you hold |
| [Aave v3](https://aave.com/docs) | Pooled Supply Markets | Supply APY, utilization, and available liquidity |
Ozmium lists the full set so you can compare before committing, rather than only surfacing positions
you already have.
{{protocols:morpho,aave}}
## Supplying
1. Choose a vault and review its live APY, its underlying asset, and its size.
2. Enter an amount.
3. Approve the token if this is the first supply from this wallet. Smart wallets batch this.
4. Sign. You receive vault shares (ERC-4626) or aTokens (Aave) representing your position.
5. Yield accrues to the position continuously. There is nothing to claim on a per-block basis.
## Withdrawing
Withdrawal redeems your shares back to the underlying asset. Two things can delay it:
- **Utilization.** If nearly all supplied assets are currently borrowed, available liquidity for
withdrawal is low until borrowers repay or new supply arrives. Lending markets are supposed to do
this, and it resolves as borrowers repay.
- **Market conditions.** During volatility, utilization spikes. Plan around it rather than assuming
instant exit.
## Reading APY Honestly
- **APY is a snapshot of this moment.** It floats with utilization and can change block to block.
- **The displayed figure is an estimate.** Ozmium shows what the protocol reports at read time.
- **Higher yield is higher risk, always.** There is no exception to this in lending. A vault paying
more is either taking more collateral risk, holding a thinner asset, or subsidising the rate.
- **Compare net of everything.** Gas to enter and exit matters on small positions.
## Risks Worth Naming
Supplying is lower risk than leverage, not zero risk:
- **Smart-contract risk.** Every vault is code. Morpho and Aave publish independent third-party
audits, which reduces this risk without eliminating it.
- **Curator risk.** A Morpho vault is configured by a curator who chooses which markets it lends
into. A misconfigured or aggressive curator changes the risk profile of your deposit.
- **Bad debt.** If collateral falls faster than liquidators can act, a market can be left with debt
it cannot recover. Suppliers absorb that.
- **Oracle risk.** Bad price data can cause mispriced liquidations in either direction.
- **No insurance.** This is not a bank deposit. It is not covered by the FDIC, SIPC, or any
government program.
## FAQ
{{direct}}
### Where does the yield in a lending vault come from?
Borrowers post collateral worth more than they borrow and pay interest on the loan. That interest,
minus the protocol's share, is your yield. There is no other source, which is why a rate far above
what borrowers plausibly pay is a signal to ask what else is going on.
### Can I withdraw from a vault at any time?
Usually, but not always instantly. If nearly all supplied assets are currently borrowed, available
withdrawal liquidity is low until borrowers repay or new supply arrives. This is normal lending
market behavior rather than a failure.
### Is supplying to a vault safe?
Supplying carries less risk than leverage, and still carries plenty. Smart-contract failure, curator
misconfiguration, bad debt, and oracle error all apply. It is not a bank deposit and is not insured by the FDIC, SIPC, or
any government program.
### What is the difference between Morpho and Aave on Ozmium?
Morpho vaults are ERC-4626 contracts configured by a curator who chooses which isolated markets the
vault lends into. Aave v3 is a pooled supply market with protocol-level risk parameters. Ozmium lists
both with live APY so you can compare them side by side.
### Does Ozmium take a cut of my yield?
No. Ozmium is an interface. The yield you see is the protocol's own reported rate, and Ozmium takes
no fee on deposits, withdrawals, or accrued interest.
## For Agents
- `GET /v1/earn/vaults` - the Morpho and Aave vault list with live APY.
- `POST /v1/tx/earn/deposit` and `/v1/tx/earn/withdraw` - ERC-4626 supply and redeem calldata.
- `POST /v1/tx/earn/aave/supply` and `/v1/tx/earn/aave/withdraw` - Aave supply and withdraw calldata.
See [Endpoint Catalog](/agents/endpoints/).
## Related
- [Loan](/guides/borrow/) - the other side of the same market
- [Liquidity](/guides/liquidity/) - fee income instead of interest income
- [Security And Trust](/company/security/) - contract addresses and audit status
---
# Wallets and Base
> How to get a wallet on Base mainnet, which wallet types Ozmium supports, and what EIP-5792 smart wallets change about approvals and gas sponsorship.
URL: https://docs.ozmium.org/start/wallets-and-base/
Markdown: https://docs.ozmium.org/start/wallets-and-base/index.md
Keywords: base wallet setup, eip-5792 smart wallet, base account passkey, base mainnet chain 8453, self-custodial defi
Updated: 2026-07-27
Ozmium is self-custodial, and it never creates, stores, or accesses a key on your behalf. You
do not need one to browse the app - see [Quickstart](/start/quickstart/) for what preview mode shows -
but you do need one to transact. If you do not have a wallet on Base yet, this page gets you one.
## Why Base Only
Base is an Ethereum layer-2 network, chain id 8453, incubated by Coinbase and secured by Ethereum.
Ozmium is a web interface built around the Base ecosystem. It is not itself a smart contract and does
not live on the chain. It reads Base state and constructs transactions that your wallet signs.
Deploying against a single network is deliberate.
**One verifiable address set.** Every contract Ozmium can reach is a single Base mainnet address,
listed in [Security And Trust](/company/security/). No chain-switching, no risk of signing on the
wrong network.
**No bridge dependency.** Cross-chain bridges have been the largest single category of loss in this
industry. Ronin, Wormhole, Nomad, and Harmony together account for well over a billion dollars in
bridge exploits. Ozmium does not operate a bridge, does not route through one, and does not ask you
to trust one.
**Costs that make active management sensible.** Gas on Base is low enough that modest positions and
frequent adjustment remain economically rational, rather than being priced out by settlement costs.
That is the point of the network, and Base states it plainly:
## Moving Funds to Base
If your assets sit on Ethereum mainnet or elsewhere, three routes:
| Route | Use When |
|---|---|
| [Base Bridge](https://bridge.base.org) | Assets Are on Ethereum Mainnet |
| Exchange Withdrawal | Your exchange supports Base withdrawals directly. Usually cheapest |
| In-app Deposit | Buying with card, Apple Pay, or bank. See [Transfers](/guides/deposits-and-withdrawals/) |
Once funds are on Base, you can acquire OZ in a single swap, either in the app or directly on
[Uniswap](https://app.uniswap.org/swap?chain=base&outputCurrency=0x148313dcdb7a7111ebefa4871f6a7fef34833b07).
The OZ/USDC pool on [Aerodrome](https://aerodrome.finance) is the other venue. See
[OZ Token](/token/oz/) for what holding it does.
## Getting an Account
The sign-in panel offers three routes:
1. **Sign In With Base.** You already have a Base account, whether through the browser extension, the
[Base App](https://base.app/invite/ozbeta/D1H4FT25), or the email and passkey it was created with. The Base SDK window handles all three.
2. **Create a Base Account.** A brand new wallet from an email and a passkey, made right there in the
app. No seed phrase to write down and lose.
3. **Mini-apps and more ways in.** An injected wallet you already run, or Ozmium opened inside the
Base App or [Farcaster](https://farcaster.xyz/~/code/1914H5), where the host wallet is already connected.
Both Base options open the same SDK window, which offers sign-in and account creation together.
{{signup}}
Starting from scratch? [Create a Base account through Ozmium](https://base.app/invite/ozbeta/D1H4FT25 "Create a Base App account with the Ozmium referral - applies current Base incentive programs and a standing fee discount.").
Signing up through that link enrolls you in whatever incentive programs Base is running at the time,
such as rebates, and a fee discount applies regardless. Base App also pays rewards on idle USDC held
in the wallet.
### Adding Base to an Existing Wallet
Most wallets detect Base automatically. If yours needs it entered manually:
| Field | Value |
|---|---|
| Network Name | Base |
| RPC URL | `https://mainnet.base.org` |
| Chain ID | `8453` |
| Currency Symbol | `ETH` |
| Block Explorer | `https://basescan.org` |
To add OZ as a token in your wallet:
| Field | Value |
|---|---|
| Contract Address | `0x148313dcdb7a7111ebefa4871f6a7fef34833b07` |
| Symbol | `OZ` |
| Decimals | `18` |
Once Base is selected, connect and you are done.
## Supported Wallet Types
| Type | What It Is | Notes |
|---|---|---|
| Injected EIP-1193 | Standard Browser Extension Wallets | The classic path. One confirmation per action. |
| EIP-5792 Smart Wallet | Smart Contract Account with Batching | Approve and act in a single confirmation; actions can be gas-sponsored. |
| [Base Account](https://docs.base.org/base-account) | Coinbase's Base-native Account | Passkey based, no seed phrase to lose. |
| Base App / Farcaster Host | Mini-app Environment | The host wallet is already connected when Ozmium opens inside it. |
## What Smart Wallets Change
On an EIP-5792 smart wallet, Ozmium batches the ERC-20 approve and the action itself into one
confirmation. Practically:
- Fewer signatures. A leveraged open that used to be approve-then-open is one tap.
- Fewer stuck states. You cannot end up approved-but-not-executed because the batch either lands or
reverts as a unit.
- Gas can be sponsored by the host, so a first-time user without ETH is not immediately blocked.
On an injected wallet you will see the individual steps instead. Nothing is lost, it is just more
confirmations.
## Passkeys and Your Data
If you sign in with a passkey, the key pair lives on your own device under your control. Ozmium never
sees it, and deleting the passkey from your device removes it from Ozmium as well.
Ozmium does not collect, store, sell, or share personal information, and runs no advertising or
behavioral tracking. There is no account to create and no profile behind it. The full data statement
is in [Terms And Risk](/company/terms/).
## The Underlying Networks
Everything below is operated by someone other than Ozmium, and every one of them is worth reading
directly.
{{protocols:base,coinbase}}
## Security Habits Worth Having
- **Keep a spending wallet separate from a holding wallet.** The wallet you connect to any dApp
should not be the wallet holding everything you own.
- **Review approvals.** An unlimited ERC-20 approval persists until revoked. Revoke ones you no
longer use.
- **Verify addresses against a second source.** Contract addresses are listed in
[Security And Trust](/company/security/) and on the app's own Terms sheet. Cross-check them against
each protocol's official documentation before signing something large.
- **Never share a seed phrase.** Ozmium will never ask for one. Nothing legitimate ever will.
---
# Loan
> Collateralized borrowing on Morpho and Aave through Ozmium - floating versus fixed rates, health factor and LLTV, liquidation mechanics, and staying solvent.
URL: https://docs.ozmium.org/guides/borrow/
Markdown: https://docs.ozmium.org/guides/borrow/index.md
Keywords: borrow against crypto base, morpho blue borrow, fixed rate defi loan, health factor liquidation, morpho midnight fixed term
Updated: 2026-07-27
Borrowing lets you access liquidity without selling the asset you hold. You post collateral, you draw
a loan against it, and you keep exposure to the collateral while you use the borrowed funds.
Both rails are available. **Variable rate** runs on [Morpho Blue](https://docs.morpho.org) and [Aave v3](https://aave.com/docs), where the cost moves with
utilization and you can repay whenever you like. **Fixed rate** runs on [Morpho Midnight](https://docs.morpho.org), where the
cost and the maturity are both settled at open. Variable is the default and the deeper market; fixed
is the one to reach for when you need to know the number in advance.
The cost of either is liquidation risk. Understand it before you draw.
## Variable Rate
Floating-rate borrowing runs on Morpho Blue markets and Aave v3. The rate moves with utilization: as
more of a market's supply is borrowed, the rate rises to attract new supply and discourage new
borrowing.
The lifecycle in Ozmium:
1. **Supply collateral.** Deposit the asset backing your loan.
2. **Borrow.** Draw against it, staying under the market's LLTV.
3. **Repay.** Pay down principal and accrued interest at any time.
4. **Withdraw collateral.** Once debt is cleared or health allows.
Each step is its own transaction, and each is visible in the app with live health readouts.
## Fixed Rate
Fixed-rate, fixed-term borrowing runs on Morpho Midnight books. Instead of a floating utilization
curve, you take liquidity from an order book at a rate that locks at execution to the market's stated
maturity.
Ozmium's fixed-rate borrow builder quotes the live bid book for your target size and encodes the
takes in order, clamped by a slippage-guarded worst price. In plain terms: it walks the book for you
and refuses to fill above the worst rate you accepted.
Fixed rate is the right choice when you need cost certainty over a known horizon. Floating is right
when you expect rates to fall or plan to repay quickly.
## Health Factor and LLTV
**LLTV** is the liquidation loan-to-value of the market - the maximum ratio of debt to collateral
value before liquidation becomes possible.
**Health factor** is where you actually sit relative to that limit. Above 1 you are solvent. At or
below 1 your position can be liquidated by anyone, permissionlessly, for a bonus.
Ozmium shows both, plus the number that actually matters day to day: **how far the market can move
against you before liquidation**. A health factor of 1.4 means nothing intuitive. "This position
liquidates if ETH drops 22 percent" means something you can act on.
## Liquidation
:::danger Liquidation is mechanical and immediate
Liquidations are enforced onchain by Morpho or Aave, not by Ozmium. Nobody warns you, nobody calls
you, and nothing pauses while you find your phone. There is no grace period and no appeal.
:::
Practical defense:
- **Borrow well under the limit.** Drawing to the maximum LLTV means any adverse move liquidates you.
- **Watch volatile collateral harder.** The more volatile the collateral, the more headroom you need.
- **Interest accrues.** A position that is safe today drifts toward liquidation over time even if the
price never moves, because debt grows.
- **Repay early, not late.** Deleveraging into strength is cheap; deleveraging into a crash is not.
## Costs
| Cost | Notes |
|---|---|
| Borrow Interest | Floating markets accrue continuously; fixed markets lock at execution |
| Liquidation Penalty | Charged to you if you get liquidated, paid to the liquidator |
| Gas | Each lifecycle step is a transaction |
## Risks Worth Naming
- **Total loss of collateral is possible** in a sharp move against a highly leveraged position.
- **Rate risk** on floating markets: your cost can rise without warning.
- **Oracle risk**: liquidations are triggered by oracle prices, not by the price you see on an
exchange screen.
- **Bad debt** can affect the market you borrowed from.
- **No grace period.** Onchain liquidation is immediate and mechanical.
### Underlying Protocols
{{protocols:morpho,aave}}
## FAQ
{{direct}}
### What is a health factor?
Health factor measures how far a borrow position is from liquidation. Above 1 the position is
solvent; at or below 1 anyone can liquidate it permissionlessly for a bonus. Ozmium also shows the
more useful figure: how far the market can move against you before that happens.
### What is the difference between floating and fixed rate borrowing?
Floating rates move with market utilization and can rise without warning. Fixed rates lock at
execution to a stated maturity through Morpho Midnight books, giving cost certainty over a known
horizon. Floating suits quick repayment; fixed suits planned spending.
### Can I be liquidated even if the price never moves?
Yes. Interest accrues continuously, so debt grows while collateral value stays flat. A position that
is safe today drifts toward liquidation over time if you leave it alone.
### Does Ozmium decide when I get liquidated?
No. Liquidation is enforced onchain by Morpho or Aave according to the market's LLTV and the oracle
price. Ozmium has no discretion, cannot pause a liquidation, and does not liquidate anyone.
### How much should I borrow relative to my collateral?
Well under the market's LLTV. Drawing to the maximum means any adverse move liquidates you
immediately. The more volatile the collateral, the more headroom you need.
## For Agents
- `GET /v1/loan/markets` - floating-rate markets with LLTV, borrow APY, and liquidity.
- `GET /v1/loan/fixed` - every live Morpho Midnight fixed-rate book with maturity and both sides'
implied APRs.
- `GET /v1/loan/analysis/{address}` - borrow-position risk analysis for a wallet.
- `POST /v1/tx/loan/*` and `POST /v1/tx/fixed/*` - the full borrowing lifecycle as calldata.
See [Endpoint Catalog](/agents/endpoints/).
## Related
- [Earn](/guides/earn/) - the supply side of these markets
- [Risk](/guides/leverage/) - a different way to take the same risk
- [Terms And Risk](/company/terms/)
---
# Security and Trust
> Ozmium's custody model, honest audit status, the full contract disclosure, privacy and crash-report handling, and how to report a vulnerability privately.
URL: https://docs.ozmium.org/company/security/
Markdown: https://docs.ozmium.org/company/security/index.md
Keywords: ozmium security, defi interface audit status, contract disclosure base, non-custodial verification, report vulnerability defi
Updated: 2026-07-27
This page is written to be checkable. Where a claim can be verified onchain, the verification method
is given instead of an assurance.
## The Custody Model
Ozmium is self-custodial. It never holds, controls, or has access to your funds or keys. Every
deposit, swap, loan, and leveraged position is initiated and signed in your own wallet, which shows
the final confirmation before anything happens.
The falsifiable test:
> If Ozmium ceased to exist right now, every position you hold remains yours and remains manageable
> directly at the underlying protocol.
Ozmium passes because it operates no contract that holds user funds. It reads public state and
produces calldata. Your wallet is the only signer. The chain is the only enforcer.
## What You Can Verify Before Signing
Ozmium builds transactions against a fixed set of third-party contracts, and every one of them is on
a published list. In the app, a **seal** marks each protocol that publishes independent third-party
audits of the contract being called.
That seal is a claim about the destination, not about this interface. The distinction is kept
deliberately, because they are different things and only one of them has been audited by an outside
firm.
The protocols Ozmium routes to - **[Gains Network](https://gains.trade), Morpho, Aave, Uniswap, and [Aerodrome](https://aerodrome.finance)** - each
publish their own audit reports. The Ozmium interface layer has not had a formal third-party audit;
independent review of it is ongoing work. Non-custody limits what that exposure can reach, since the
interface holds nothing and signs nothing, but it is a structural mitigation rather than a substitute
for review.
Every transaction is inspectable in your wallet and on [Basescan](https://basescan.org) before you approve it, which is the
protection that does not depend on trusting anyone's description of anything.
## The Contract Disclosure
Every contract the interface can build a transaction against, on one list, so a user or an auditor
can verify the destinations without reading the source.
A seal in the app marks a protocol that publishes independent third-party audits **of that
contract**. It is never a claim about the Ozmium interface, which is unaudited and says so.
| Contract | Protocol | What Ozmium Asks It to Do | Third-party Audited |
|---|---|---|---|
| Aave V3 Pool | Aave | Supplies, withdraws, borrows, and repays against Aave reserves | Yes |
| [Morpho Blue](https://docs.morpho.org) | Morpho | Lends and borrows on isolated Morpho markets | Yes |
| Gains Network Diamond | Gains Network ([gTrade](https://gains.trade)) | Opens, modifies, and closes leveraged positions | Yes |
| [Permit2](https://docs.uniswap.org/contracts/permit2/overview) | Uniswap | Holds the token allowance a swap spends, under a signature you sign per swap with its own amount and deadline | Yes |
| Aerodrome Router | Aerodrome | Adds and removes liquidity on Aerodrome pools | Yes |
| Uniswap V3 Position Manager | Uniswap | Mints and manages concentrated liquidity positions | Yes |
| USDC | Circle | The settlement token for lending, perps, and most swaps | Yes |
| OZ Token | [Clanker](https://clanker.world) | The project's own ERC-20 on Base, deployed by Clanker v3.1 as a standard token and source-verified onchain | **No** |
**Live addresses for every row are published on the app's own Terms sheet** at
[ozmium.org](https://ozmium.org), where the list is derived directly from the modules that call each
address rather than hand-copied. A hand-copied list is a claim about the code, and claims drift. The
app's list cannot disagree with what the app actually calls.
Verify any address against the protocol's own documentation before you sign.
### On the OZ Token Row
The OZ token is marked **not audited**, deliberately. The Clanker v3.1 contracts are public with
published documentation, but no third-party audit report is published for them.
OZ is **source-verified onchain** - anyone can read the deployed bytecode against the published
source. That is a real and checkable property, and it is a weaker claim than audited. The two are not
shown as the same thing.
### Runtime-Resolved Addresses
Two destinations are chosen at runtime rather than pinned at build time. They are called out rather
than hidden, because "we only ever call contracts we chose" is the interesting claim and these are
its only exceptions:
- **Morpho vaults.** Individual vaults are ERC-4626 contracts published by Morpho and read at
runtime. Each is shown with its address before you deposit.
- **Swap settlement.** The swap route quotes a settlement contract from the Coinbase Developer
Platform. The interface refuses to approve any spender other than the pinned Permit2 address.
## Token Address
There is only **one** token for Ozmium. The Base ERC-20 address is:
`0x148313dcdb7a7111ebefa4871f6a7fef34833b07`
If this ever changes, the change will be indicated officially on the app's Terms sheet and here. Any
other address claiming to be OZ is not OZ.
## Operational Wallets
Ozmium holds no user funds, so none of this touches you. For its own accounts, the project separates
wallets by role, keeps value at rest behind a Safe with transaction protections, and does not publish
operational addresses.
That last choice has a cost worth naming: circulating supply and treasury holdings cannot be
independently verified from this page. Total supply and burned supply both can - see
[OZ Token](/token/oz/).
## Data and Privacy
- Ozmium does **not** collect, store, sell, or share personal information.
- No advertising, no behavioral tracking of any kind.
- No account to create and no profile behind one.
- If you sign in with a passkey, the key pair lives on your own device under your control. Ozmium
never sees it, and deleting it from your device removes it from Ozmium as well.
**Crash reports.** When something breaks, the app sends a diagnostic report so it can be fixed: the
error, the page, the app build, and basic browser details such as viewport and connection type. It
records which **kind** of wallet is connected - whether the browser has an injected provider at all -
and never your wallet address, your balance, or any identifier tied to you. Reports are grouped by
error, not by person, and no profile is built from them.
**Third-party hosts.** Opened inside a host app such as the [Base App](https://base.app/invite/ozbeta/D1H4FT25) or [Farcaster](https://farcaster.xyz/~/code/1914H5), that platform may
record its own basic, aggregated, deidentified usage counts under its own policy. Those platforms and
the protocols listed above are independent of Ozmium.
## Engineering Rules that Are Security Rules
These are enforced in the codebase rather than aspired to:
- **Secrets never in code.** Environment files and platform secret storage only. Never in committed
files, never in configuration variables intended for public values.
- **Never fabricate.** No fabricated zeros, no invented balances on an RPC failure. Last-good is
retained and marked. A confident `$0.00` over a broken read is the most dangerous state a finance
UI can render.
- **Base mainnet only.** One chain, one address set, no bridge introduced by us.
- **Pinned spenders.** The interface refuses to approve any spender other than the addresses it
chose.
## Reporting a Vulnerability
If you have found a security issue, report it privately first. Do not open a public issue and do not
post it in Discord.
- Email: **hello@ozmium.org** with `SECURITY` in the subject line.
- A `security.txt` is published at
[ozmium.org/.well-known/security.txt](https://ozmium.org/.well-known/security.txt).
Include what you found, how to reproduce it, and the impact you believe it has. You will get an
acknowledgment.
Please do not test against other users' funds, do not perform denial-of-service testing, and do not
access data that is not yours. Everything else is fair game.
## FAQ
### Is Ozmium audited?
The underlying protocols Ozmium routes to - Gains Network, Morpho, Aave, Uniswap, and Aerodrome -
publish independent third-party audits of their contracts. The Ozmium interface itself has not
undergone a formal third-party audit. Non-custody is a structural mitigation, not an audit, and the
two are not presented as the same thing.
### Can Ozmium access or move my funds?
No. Ozmium operates no contract that holds user funds, never signs on your behalf, and cannot move
anything you own. Every transaction is signed in your own wallet, which shows the final confirmation.
### What data does Ozmium collect?
None that identifies you. There is no account, no advertising, and no behavioral tracking. Crash
reports carry the error, the page, the app build, and basic browser details, plus which kind of
wallet is connected - never your address, your balance, or any identifier tied to you.
### How do I verify a contract address before signing?
Live addresses are published on the app's own Terms sheet, derived directly from the modules that
call them so the list cannot drift. Cross-check any address against the protocol's own documentation
and inspect the destination in your wallet before approving.
### Is the OZ token contract audited?
No. OZ was deployed by Clanker v3.1 as a standard token and is source-verified onchain, meaning
anyone can read the deployed bytecode against the published source. That is a real property and a
weaker claim than audited, so it is marked as unaudited.
### How do I report a security vulnerability?
Email hello@ozmium.org with `SECURITY` in the subject line, or use the contact in
`ozmium.org/.well-known/security.txt`. Report privately first - do not open a public issue or post it
in Discord.
## What Ozmium Cannot Protect You From
A security page that only lists its own strengths is a marketing page wearing a lab coat, so here is
the other column:
- **Your own signature.** If you approve a malicious transaction from another site, Ozmium cannot
undo it.
- **Underlying protocol failure.** Every protocol Ozmium routes to is code that can fail.
- **Oracle error.** Bad price data can cause mispriced liquidations in either direction.
- **Market risk.** Liquidation is arithmetic enforced onchain. Nothing in the interface changes it.
- **Phishing.** Verify you are on `ozmium.org`. Ozmium will never ask for a seed phrase.
## Related
- [Terms And Risk](/company/terms/)
- [Wallets And Base](/start/wallets-and-base/)
---
# Prop
> Ozmium's gated action surface for qualified OZ holders and agents - how membership is proven onchain, the two authorization rails, and why paying is not authorizing.
URL: https://docs.ozmium.org/guides/prop-desk/
Markdown: https://docs.ozmium.org/guides/prop-desk/index.md
Keywords: ozmium prop desk, onchain proven membership, oz burn authorization, paytxhash burntxhash, token gated api access
Updated: 2026-07-27
The prop desk is a set of actions closed to non-members. Membership is not a subscription, a login,
or a claim in a request body. It is proven by a real onchain OZ transfer that anyone can verify.
## Qualifying, and Then Earning Allotment
Two different things happen here, and the page used to run them together.
**Qualifying** is the door. A wallet becomes a qualified member at **$500 of combined hold, burned,
and sent OZ value**. All three count, so burning toward the ladder builds desk standing rather than
being a separate sacrifice. The check runs against onchain state, so there is nothing to apply for and
nothing to renew.
**Allotment** is what you get once you are inside, and it is not fixed. Your allotment caps the size
and leverage of each action you can take, and it scales with **lifetime OZ burned** and your **onchain
record**. Burn more, or trade better, and the cap rises.
**Performance sets the range.** Allotment is not only a size cap. Your running performance score and
your record of activity across the app together determine which actions are open to you at all. A
wallet with a thin record gets the conservative end of the book; a wallet that has traded well and
used the app consistently unlocks the wider one. Both inputs are read from the chain, so neither can
be argued with, bought around, or reset by asking.
So the desk is not a binary gate with a subscription behind it. It is a threshold to enter and then a
continuously earned line of credit, priced by what you have burned, how you have traded, and how much
of the app you actually use.
It is a game of skill, played collectively. There is no promised reward, no yield attached to
participation, and no payout schedule. What exists is one shared model that performs better as the
people trading it get better. The desk runs on OZ because every action in it is authorized by an OZ
transfer, and that is the entire relationship between the token and the game.
## The Agent Trades Its Own Book
The desk is not a simulation with a scoreboard bolted on. **Ozwald manages its own wallet and trades
its own funds**, under the same allowance system every other member is bound by, and the prop game
runs on that same mechanism rather than a parallel one built for it.
That matters for three reasons, and they are practical rather than thematic.
**The rules are tested by something that has to live under them.** An allowance system nobody is
actually constrained by drifts, because nothing pushes back. When the operator's own agent is subject
to the same allowlist, cooldowns, and size ceilings, a rule that is wrong becomes obvious quickly and
at the author's expense.
**Agents and people compete on the same terms.** There is no separate machine tier and no privileged
path. An autonomous participant proves membership with an onchain OZ transfer exactly as a person
does, and its performance score is computed the same way, which is what makes a mixed leaderboard
mean anything.
**It demonstrates the capability the API sells.** Every builder endpoint returns calldata an agent
signs and broadcasts from its own wallet. Ozwald doing precisely that, with real funds and real
consequences, is the reference implementation. If the calldata were wrong, the agent would be the
first to pay for it.
The wider point is that this is what a **non-custodial agent economy** looks like in practice. The
desk holds nothing. Each participant, human or software, signs from a wallet it controls, proves
standing onchain, and earns a wider range of actions by performing rather than by asking.
## Two Rails, One Proof
Every prop action requires a real onchain OZ transfer as its authorization:
| Actor | Rail | Field Passed |
|---|---|---|
| Human | Burn OZ to the dead address. | `burnTxHash` |
| Agent | Transfer OZ to the desk recipient. | `payTxHash` |
Both hashes are verified as an actual ERC-20 `Transfer` from the member wallet to the expected
destination. Neither can be forged by sending a field, and you cannot act on another wallet's behalf.
The same allowlist, cooldowns, and eligibility gates apply on either rail.
## Payment Is Not Authorization
:::warning Two proofs, both required
The x402 fee alone does not authorize a prop action. The x402 payment buys the API call; the OZ
transfer authorizes the action. A call arriving without a valid `payTxHash` or `burnTxHash` is
refused with `bad payTxHash` or `bad burnTxHash`.
:::
## The Endpoints
| Endpoint | Price | Purpose |
|---|---|---|
| `POST /v1/prop/quote` | $0.005 | OZ cost, match factor, and whether your wallet qualifies. Needs `actionId` (for example `trade.open`) plus that action's parameters. |
| `POST /v1/prop/execute` | $0.01 | Run the action. Needs `actionId`, the action's parameters, and `payTxHash` or `burnTxHash`. |
Quote first, always. It tells you the cost and your eligibility before you spend anything on an
execute that would be refused.
## Why It Is Built This Way
An API key can be leaked, shared, or stolen, and revoking it is an administrative act by the
operator. An onchain transfer cannot be replayed by someone else, cannot be forged, and requires no
account system to administer.
It also means the access rule is auditable by anyone. You do not have to trust our description of who
qualifies; you can check the chain.
## Related
- [OZ Token](/token/oz/) - what else holding OZ does
- [x402 Payments](/agents/x402/) - the payment layer that is not the authorization layer
- [Endpoint Catalog](/agents/endpoints/)
---
# Terms and Risk
> Terms of use and full risk disclosure for the Ozmium interface - public beta status, non-custody, data handling, third-party protocols, and the risk of loss.
URL: https://docs.ozmium.org/company/terms/
Markdown: https://docs.ozmium.org/company/terms/index.md
Keywords: ozmium terms, defi risk disclosure, public beta terms of use, non-custodial interface terms, not financial advice notice
Updated: 2026-07-27
:::note The app version governs
This page mirrors the Terms and Risk sheet shown inside the Ozmium app. Where the two differ, the
version displayed in the app at [ozmium.org](https://ozmium.org) governs.
:::
## Public Beta
The Ozmium Organization and the ozmium.org interface are in **public beta**. The interface is under
active development and may change or be unavailable at any time. Use at your own risk.
Onchain features are an aggregation service that uses official contracts from major audited
protocols. If you are concerned about performance risk from the ozmium.org interface, manage your
positions directly from the official platforms of those protocols.
## Token Address
There is only one (1) token for Ozmium, and the Base ERC-20 address is:
`0x148313dcdb7a7111ebefa4871f6a7fef34833b07`
If this changes we will officially indicate the change here and in the app.
## Non-Custodial
Ozmium is a self-custodial interface on Base. We never hold, control, or have access to your funds or
keys. Every deposit, swap, loan, and leveraged position is initiated and signed in your own wallet,
which shows the final confirmation.
## Your Data Stays Yours
We do not collect, store, sell, or share your personal information, and we run no advertising or
behavioral tracking of any kind. There is no account to create and no profile behind it.
If you sign in with a passkey, the key pair lives on your own device under your control. We never see
it, and deleting the passkey from your device removes it from us as well.
## Crash Reports
When something breaks, the app sends a diagnostic report so it can be fixed: the error, the page, the
app build, and basic browser details such as viewport and connection type. It records which **kind**
of wallet is connected - whether the browser has an injected provider at all - and never your wallet
address, your balance, or any identifier tied to you. Reports are grouped by error, not by person,
and we build no profile from them.
## Third-Party Platforms
Opened inside a host app such as the [Base App](https://base.app/invite/ozbeta/D1H4FT25) or [Farcaster](https://farcaster.xyz/~/code/1914H5), that platform may record its own basic,
aggregated and deidentified usage counts under its own policy.
Those platforms, the protocols listed below, and any site you reach from here are independent of us.
We do not control their content, their connections, or what they collect, and we are not responsible
for them.
## Third-Party Protocols
Staking, earning, and borrowing are powered by [Morpho](https://morpho.org/) and
[Aave](https://aave.com/); leverage by [Gains Network (gTrade)](https://gains.trade/); swaps and
on/off-ramps by
[Coinbase Developer Platform](https://www.coinbase.com/developer-platform); liquidity by
[Aerodrome](https://aerodrome.finance/) and [Uniswap](https://uniswap.org/).
These are independent services, not offered by, operated by, or affiliated with this site. We are not
a bank, broker, dealer, exchange, adviser, or your counterparty, and we do not solicit or recommend
any transaction.
## Network and Contracts
The interface operates on **Base** (chain ID **8453**), an Ethereum layer-2 network. It builds
transactions only against a published list of contracts, each one published and operated by the
protocol named beside it.
A seal marks a protocol that publishes independent third-party audits of its contracts. **It is not a
claim about this interface, which is in beta and has not been audited.** Verify any address against
the protocol's own documentation before you sign.
The full contract list is in [Security And Trust](/company/security/), with live addresses on the
app's own Terms sheet.
## Risk of Loss
DeFi carries risk, including smart-contract failure, oracle error, curator or market
misconfiguration, illiquidity, bad debt, and the **partial or total loss of funds**.
Borrowing can liquidate your collateral. Leverage is high-risk: adverse price moves, funding, and
borrow fees can liquidate a position and cause total loss of collateral rapidly and without notice.
**This is not a bank deposit and is not insured by the FDIC, SIPC, or any government program.**
## Estimates
Displayed prices, APY and APR, liquidation prices, fees, and PnL are **estimates** that change with
the market. Liquidation price excludes rollover and borrow fees.
A past price range does not bound future prices; markets exceed their history routinely.
Nothing here is financial, investment, legal, tax, or accounting advice, an offer, or a solicitation.
## Records and Tax
Ozmium issues no statements, no forms, and no year-end notices. It is not a broker, does not report
to any tax authority on your behalf, and holds no record of your activity that you do not already
hold yourself.
Your records are the chain. Every swap, deposit, withdrawal, borrow, repayment, liquidation, and
position close is a transaction under your own address on Base mainnet, permanently readable by
anyone. Free block explorers, including [Basescan](https://basescan.org) and
[Etherscan](https://etherscan.io), let you look up any address or transaction hash and export a
complete history. That record is your receipt, and it is more durable than anything a company could
send you.
Disposing of an asset may create a taxable gain or a deductible loss depending on where you live and
what your situation is, and the same is true of receiving yield, incurring a liquidation, or closing
a leveraged position. Some of those outcomes work in your favor. Which ones, and how they are
treated, is a question for a qualified professional in your jurisdiction. Nothing on this site is tax
advice, and Ozmium neither tracks nor manages any obligation you may have.
## Experimental Features
The technical marker feeds - including `/v1/ta` and `/v1/ta/scan` and the signal displays in the app -
are **experimental and explicitly unproven**. There is no established out-of-sample edge, and none of
it is financial advice. Corroborate with news and cross-asset context before acting on any of it.
## Agent API
The Ozmium agent API is a paid service for automated clients. Payment over x402 buys the API call
only. It confers no ownership, no claim on revenue, and no authorization for gated prop desk actions,
which require a separate onchain OZ transfer.
Prices may surge during network congestion. The authoritative price for any call is the one in its
402 challenge.
## Eligibility and Law
You are solely responsible for complying with the laws of your jurisdiction, including any that
restrict leveraged or derivative products for certain persons.
The interface is provided **"as is"** and **"as available"** with no warranties. To the maximum extent
permitted by law, this site and its operators disclaim all liability for any loss arising from use of
these features.
Use at your own risk and consult a licensed professional.
## Regulatory Clarity
The rules that govern self-custodial software in the United States are still being written. The
**Digital Asset Market Clarity Act** would settle a question that currently has no settled answer:
whether publishing software that constructs a transaction, without ever holding a customer's assets,
makes the publisher a broker or an exchange. Under the framework the bill proposes, it does not.
That distinction is the difference between an application like this one existing and not existing.
Ozmium supports its passage, and if you use software of this kind, your view carries weight with the
people voting on it.
[Stand With Crypto](https://www.standwithcrypto.org/join/LBKECAq8oAZR) is the advocacy organization
tracking the legislation and organizing constituent contact around it. Joining is free, takes about a
minute, and is not a financial commitment of any kind. Nothing about your standing as an Ozmium user
changes either way.
## Changes to These Terms
These terms may change as the interface develops. Material changes will be reflected here and in the
app's Terms sheet. Continued use after a change constitutes acceptance of it.
## Contact
hello@ozmium.org
## Related
- [Security And Trust](/company/security/)
- [Risk](/guides/leverage/) - read before using leveraged products
---
# Trade
> How to swap tokens on Base with Ozmium - getting a quote, setting slippage, what the three costs are, and what to do when a swap fails.
URL: https://docs.ozmium.org/guides/trade/
Markdown: https://docs.ozmium.org/guides/trade/index.md
Keywords: swap tokens on base, base dex aggregator, spot swap slippage, permit2 approval, fee-netted arbitrage base
Updated: 2026-07-27
A swap trades one token for another at the current price. There is no leverage, nothing to liquidate,
and no position left over afterward, which makes it the easiest place to start.
## Making a Swap
1. Pick the token you are paying with and the token you want.
2. Enter an amount. You will see the expected output, the route, and the fees before you commit to
anything.
3. Approve the token if this is your first time spending it from this wallet. On a smart wallet the
approval is bundled with the swap, so it is one confirmation instead of two.
4. Sign. Your wallet shows the final transaction.
5. The transaction hash links to [Basescan](https://basescan.org) when it lands.
Routing and pricing come from the [Coinbase Developer Platform](https://www.coinbase.com/developer-platform) Trade API using Permit2.
You may also see a line like the one in that screenshot, warning that you are selling ETH near its
52-week low. Those appear when something about the trade is worth a second look. They do not block
anything.
## Slippage
Prices move between the moment you get a quote and the moment your transaction is included. Slippage
is how much of that movement you are willing to accept.
Set it too tight on a thin pair and your swaps will keep failing. Set it too loose on a volatile one
and you can fill well below what you expected. A failed swap costs gas but not the tokens you were
trading, so failing is usually the better of the two outcomes.
If a swap keeps reverting, that is worth reading as information about how deep the pair actually is.
## What a Swap Costs
Three separate things, often confused for each other:
| Cost | Who Charges It | Where It Shows Up |
|---|---|---|
| Network Gas | Base | Paid in ETH, separate from the trade |
| Pool or Venue Fee | The DEX Being Routed Through | Already Inside the Quoted Output |
| Price Impact | The Market | Shown in the quote; grows with order size |
Ozmium does not add a fee of its own. The app is free for people.
## Arbitrage
Ozmium also computes routes across venues and reports the spread **after** gas and pool fees rather
than before. Two numbers that look similar on a screen can be opposite in practice, and the one that
matters is the one with costs already taken out.
Agents can request these directly at `GET /v1/arbitrage`. See
[Endpoint Catalog](/agents/endpoints/).
Note what it says when there is no edge: *no route found for cbBTC arbitrage over $0.01*. A tool that
only ever finds opportunities is not measuring anything.
## Checking What Happened
The transaction hash is your receipt. Open it on Basescan and the `Transfer` events show exactly what
moved and where. Balances in the app come from onchain state rather than an optimistic guess, so if
the two ever disagree, believe Basescan.
## When a Swap Fails
**"Transaction reverted."** Usually slippage. Get a fresh quote and try again, or widen your tolerance
a little on a thin pair.
**"Insufficient allowance."** The approval did not land, or it was smaller than the swap needs.
Approve again. On an injected wallet these are two separate transactions and the first can fail
quietly.
**"Insufficient funds for gas."** You spent the ETH you needed to pay for the transaction. Keep a
small buffer you never trade.
**Output smaller than expected.** Price impact on a shallow pair. Split the order into pieces, or use
a more liquid route.
More in [Troubleshooting](/guides/troubleshooting/).
## If Something Goes Wrong
{{direct}}
### Underlying Protocols
{{protocols:coinbase,base}}
## Related
- [Charts](/guides/charts/) - reading candles, indicators, and signals
- [Earn](/guides/earn/) - putting the token to work once you hold it
- [Liquidity](/guides/liquidity/) - being on the other side of someone else's swap
- [OZ Token](/token/oz/)
---
# Glossary
> Plain-language definitions of every term used across Ozmium - onchain basics, leverage, lending, liquidity provision, and the x402 machine payment protocol.
URL: https://docs.ozmium.org/company/glossary/
Markdown: https://docs.ozmium.org/company/glossary/index.md
Keywords: defi glossary, onchain finance terms, liquidation price meaning, lltv health factor explained, x402 glossary, perpetual futures terms
Updated: 2026-07-27
Short, practical definitions. Where a term has a precise meaning inside Ozmium, that is the meaning
given here.
## Onchain Basics
**Base** - An Ethereum layer-2 network, chain id 8453. The only network Ozmium operates on.
**ERC-20** - The token standard. OZ, USDC, and every other token in the app is an ERC-20.
**Approval** - Permission you grant a contract to spend a specific ERC-20 from your wallet. Required
once per token per spender. An unlimited approval is a standing permission until revoked.
**Calldata** - The encoded instruction inside a transaction: `{ to, data, value }`. Ozmium builds
calldata; your wallet signs and broadcasts it.
**Gas** - The fee paid in ETH to include a transaction. On Base this is small but never zero unless
someone else is sponsoring it.
**Non-custodial** - The operator cannot hold, move, or freeze your assets. Ozmium is non-custodial.
**[Basescan](https://basescan.org)** - The Base block explorer. The final authority on what a transaction actually did.
## Trading
**Spot swap** - Exchanging one token for another at the current price. No leverage, no liquidation.
**Slippage** - The difference between the quoted price and the filled price. Guarded by a maximum you
set; if the market moves past it, the transaction reverts instead of filling badly.
**Perpetual (perp)** - A leveraged long or short position with no expiry date. Ozmium routes
perpetuals to [Gains Network gTrade](https://gains.trade), using USDC as collateral.
**Margin / collateral** - The USDC you post to open a leveraged position. Position size equals margin
times leverage.
**Leverage** - The multiplier on your margin. 10x on $100 of margin controls $1,000 of exposure, and
a 10 percent adverse move wipes the margin.
**Liquidation** - The forced close of a position when its margin can no longer cover losses. Enforced
onchain by the protocol, not by Ozmium.
**Liquidation price** - The market price at which liquidation occurs. Shown before you sign.
**Mark price vs index price** - `mark` is what a position fills at on Gains. `index` is the oracle
spot price liquidations are measured against. The gap between them is real and tradeable.
**Funding / rollover fee** - The ongoing cost of holding a leveraged position. It accrues against
your margin over time.
**Take profit (TP) / stop loss (SL)** - Resting instructions to close a position at a target or a
maximum loss. Ozmium can modify these on an open position without closing it.
**Pending order** - A resting limit or stop order that has not filled. It holds collateral but is not
yet a position. Conflating the two is a common integration bug.
## Lending and Borrowing
**Vault** - A pooled lending market you supply assets to in exchange for yield. Ozmium lists Morpho
ERC-4626 vaults and [Aave v3](https://aave.com/docs) markets.
**APY / APR** - Annualised yield or rate. Both float with market conditions; a displayed rate is an
estimate at the moment you read it.
**LLTV** - Liquidation loan-to-value. The maximum ratio of debt to collateral before the position can
be liquidated.
**Health factor** - How far a borrow position is from liquidation. Above 1 is solvent; at or below 1
it can be liquidated.
**Floating rate** - A borrow rate that moves with utilization of the market.
**Fixed rate / fixed term** - A borrow rate locked at execution to a stated maturity. Ozmium surfaces
these through [Morpho Midnight](https://docs.morpho.org) books.
**Bad debt** - Debt left in a market after collateral proved insufficient to cover it. A real risk in
any lending protocol.
## Liquidity
**LP (liquidity provider)** - Someone who deposits both sides of a trading pair into a pool and
collects a share of swap fees.
**vAMM** - The [Aerodrome](https://aerodrome.finance) volatile-pair pool style used for OZ/USDC.
**Concentrated liquidity** - [Uniswap v3](https://app.uniswap.org)'s model, where liquidity is placed within a chosen price
range. Ozmium's Uniswap v3 OZ/WETH position is placed at **full range** by default.
**Full range** - Liquidity spanning all prices. It earns less per dollar than a tight range but never
goes out of range, which is the only safe default for a position nobody is watching.
**Impermanent loss** - The value difference between LPing a pair and simply holding both tokens. It
is real, and it grows with divergence between the two sides.
**Fee claim** - Collecting accrued swap fees. On Uniswap v3 removal with `liquidity: 0` claims fees
without closing the position.
## OZ and the Desk
**OZ** - The Ozmium token on Base, `0x148313dcdb7a7111ebefa4871f6a7fef34833b07`, 18 decimals, 100
billion maximum supply, burn-preferred.
**onz** - The unit name for OZ. One hundred Ozmium is written 100oz.
**Burn** - Sending OZ to the dead address, permanently removing it from supply. Burns are ranked
publicly onchain.
**Burn ladder** - The public onchain ranking of wallets by OZ burned.
**Prop desk** - A gated action surface for qualified OZ holders. Access is proven by a real onchain
OZ transfer or burn, not by a claim in a request body.
## Agent API
**x402** - An HTTP payment protocol. A server answers an unpaid request with HTTP 402 and a payment
challenge; the client signs a payment and retries. Ozmium uses x402 v2, `exact` scheme, on Base.
**EIP-3009** - `transferWithAuthorization`, the USDC signature standard x402 uses. It lets a client
authorize an exact transfer without a prior approval transaction.
**Payment is authentication** - There is no signup, no API key, and no key rotation. A valid payment
is the credential.
**MCP** - Model Context Protocol. Ozmium publishes an MCP-shaped tool manifest so agent frameworks
can discover its endpoints as tools.
**llms.txt** - A plain-Markdown index of a site written for language models rather than crawlers.
Ozmium publishes one for the app and one for these docs.
---
# Liquidity
> Provide liquidity to the OZ pools on Aerodrome and Uniswap v3 - fee income, why full range is the default, impermanent loss, and claiming fees without closing.
URL: https://docs.ozmium.org/guides/liquidity/
Markdown: https://docs.ozmium.org/guides/liquidity/index.md
Keywords: oz liquidity pool, aerodrome vamm oz usdc, uniswap v3 full range, impermanent loss explained, claim lp fees without closing
Updated: 2026-07-27
Providing liquidity means depositing both sides of a trading pair into a pool so other people can
swap against it. In exchange you collect a share of every swap fee routed through that pool.
It is the other side of [Trade](/guides/trade/). Someone has to be there when a swap arrives.
## The Two OZ Pools
| Pool | Venue | Style | Notes |
|---|---|---|---|
| OZ / USDC | [Aerodrome](https://aerodrome.finance) | vAMM (Volatile Pair) | Straightforward Two-sided Deposit |
| OZ / WETH | [Uniswap v3](https://app.uniswap.org) | Concentrated liquidity, 1 percent fee tier | Ozmium places this at full range |
## Why Full Range on Uniswap v3
Uniswap v3 lets you concentrate liquidity in a price band. A tight band earns more fees per dollar
deployed - right up until the price leaves the band, at which point the position stops earning
entirely and sits fully converted into the losing side.
Ozmium defaults the OZ/WETH position to **full range**. A full-range position earns less per dollar
but never goes out of range. For a position nobody is actively watching, and especially for an
autonomous agent that will not be monitoring price, that is the only defensible default.
If you want a tighter band, manage it directly on Uniswap. Ozmium will not quietly put you in a
position that requires supervision you did not agree to provide.
## Adding Liquidity
1. Choose the pool.
2. Enter an amount. Ozmium computes the matching amount for the other side at the current ratio.
3. Approvals are prepended automatically for both sides when the live allowance is short. On the
Uniswap v3 path this is a bundled multicall, with ETH auto-wrapped and any excess refunded.
4. Sign.
## Claiming Fees without Closing
This is the part people miss.
:::tip Claim without closing
On the Uniswap v3 path, calling remove with `liquidity: 0` collects accrued fees only and leaves the
position open. That is the claim path - you never need to tear down a position to take income out of
it. For agents: `POST /v1/tx/lp/uni/remove` with `liquidity: 0`.
:::
## Impermanent Loss, Plainly
That is an open OZ/USDC position, **down $8.58 against $30.39 deposited**, reported in plain red
rather than behind a headline APR. Worth looking at before the mechanics rather than after, because it
is what providing liquidity can do.
If OZ and the paired asset diverge in price, the pool rebalances you into more of the falling asset
and less of the rising one. Compared with simply holding both tokens, you end up worse off by an
amount that grows with the divergence.
Fees offset this. Whether they offset it enough depends on volume relative to divergence, and nobody
can promise you that ratio in advance. Impermanent loss becomes permanent the moment you withdraw.
:::warning Size This By What You Are Willing To Hold
Providing liquidity converts your deposit into a shifting mix of both tokens, and that mix moves
against you as the two diverge. Commit only capital you would be content to hold as either one.
:::
{{protocols:aerodrome,uniswap}}
## Risks Worth Naming
- **Impermanent loss** as described above.
- **Smart-contract risk** in the pool contracts.
- **Thin-pool volatility.** A pool with modest depth moves hard on modest volume, in both directions.
- **Fee income is not guaranteed.** No volume means no fees, and the impermanent loss does not care.
## FAQ
{{direct}}
### What is impermanent loss?
If the two sides of a pool diverge in price, the pool rebalances you into more of the falling asset
and less of the rising one. Compared with simply holding both tokens you end up worse off, and the
gap grows with divergence. It becomes permanent the moment you withdraw.
### Why does Ozmium default the Uniswap v3 position to full range?
A tight range earns more fees per dollar until price leaves the band, at which point the position
stops earning entirely and sits fully converted into the losing side. Full range earns less but never
goes out of range, which is the only safe default for a position nobody is watching.
### Can I collect LP fees without closing my position?
Yes. On Uniswap v3, remove with `liquidity: 0` collects accrued fees and leaves the position intact.
### Which OZ pools does Ozmium support?
Aerodrome OZ/USDC as a volatile-pair vAMM, and Uniswap v3 OZ/WETH in the 1 percent fee tier at full
range. Both are reachable from the app and from the `/v1/tx/lp/*` builders.
## For Agents
- `POST /v1/tx/lp/aero/add`, `/v1/tx/lp/aero/remove` - Aerodrome OZ/USDC.
- `POST /v1/tx/lp/uni/add`, `/v1/tx/lp/uni/remove` - Uniswap v3 OZ/WETH full range.
See [Endpoint Catalog](/agents/endpoints/).
## Related
- [OZ Token](/token/oz/) - why LPing OZ is one of the token's core utilities
- [Trade](/guides/trade/)
---
# Transfers
> How to fund an Ozmium wallet and take value back out - the Coinbase on-ramp and off-ramp, sending, receiving, and what you need on Base before anything works.
URL: https://docs.ozmium.org/guides/deposits-and-withdrawals/
Markdown: https://docs.ozmium.org/guides/deposits-and-withdrawals/index.md
Keywords: fund base wallet, deposit withdraw base, coinbase onramp base, crypto off-ramp to bank, send receive base tokens, buy usdc on base
Updated: 2026-07-28
Before you can trade, earn, or borrow, you need two things sitting in your wallet on Base: a little
ETH for gas, and whatever you actually intend to use, which is usually USDC.
There are three ways to get them there.
## Buy with a Card or Bank
The app's Deposit flow uses **Coinbase Onramp**. Ozmium mints a session token, then hands you to
Coinbase's hosted checkout at `pay.coinbase.com` in a new tab. You pay by card, Apple Pay, or bank
transfer, and the asset is delivered to your wallet on Base.
Nothing routes through Ozmium. Coinbase settles the fiat side directly with you, and the crypto
arrives in the wallet you already control. Ozmium never touches either leg.
You do not need to have used Coinbase before, and you do not need to keep funds there afterward.
## Withdraw to a Bank
The same rail runs backward. **Withdraw** opens Coinbase's hosted off-ramp, sells the asset, and
settles cash to your bank. Same arrangement: hosted by Coinbase, settled directly with you.
If the ramp is unavailable you will get a plain message saying so rather than a broken screen. It
depends on Coinbase's service being configured and available in your region.
## Send and Receive Directly
If you already hold crypto somewhere else, this is usually simpler and cheaper than buying again.
**Receive** shows your address and a QR code. Withdraw to it from an exchange, making sure you pick
**Base** as the network. Sending on the wrong network is the most common way people lose funds, and no
interface can undo it.
**Send** moves a token or ETH from your wallet to any address. Check the destination character by
character before you sign; a transaction that has been included cannot be reversed by anyone.
## What You Actually Need
| Asset | Why | How Much |
|---|---|---|
| ETH on Base | Gas for Every Transaction | Balances required are nominal. Keep a buffer you never spend |
| USDC on Base | Collateral for perps, the quote asset for most things | Whatever You Plan to Use |
USDC on Base is `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`.
Running out of ETH mid-session is the single most common first-day problem. It looks like everything
suddenly failing at once, and it is resolved by holding a nominal ETH balance in reserve.
## If You Are Bridging from Another Chain
Move funds to Base using the official Base bridge or an exchange withdrawal that supports Base
directly. That step happens outside Ozmium, which does not operate a bridge.
## Related
- [Quickstart](/start/quickstart/)
- [Wallets And Base](/start/wallets-and-base/)
- [Trade](/guides/trade/)
---
# Burning OZ
> How burning OZ works on Ozmium - sending to the dead address, what The Density Ladder ranks, and how burned value counts toward prop desk standing.
URL: https://docs.ozmium.org/guides/burn/
Markdown: https://docs.ozmium.org/guides/burn/index.md
Keywords: burn oz token, density ladder ranking, dead address burn base, deflationary token supply, burn for prop access
Updated: 2026-07-28
Burning sends OZ to the dead address, `0x000000000000000000000000000000000000dEaD`. Nobody holds the
key to that address, so anything sent there is permanently out of supply.
## How to Burn
Connect a wallet, choose an amount, and sign. Your burned total updates straight from chain state
rather than from anything Ozmium stores, so it is the same number anyone else reading the chain would
compute.
Agents can build the transaction with `POST /v1/tx/burn`.
## The Density Ladder
Burning ranks your wallet on **The Density Ladder**, a public ranking derived from onchain burns. It
is not a leaderboard Ozmium maintains and could adjust; it is a view of what the chain already says.
## Burning Is Not Only a Sacrifice
Burned value counts toward [prop desk](/guides/prop-desk/) standing in two ways.
It counts toward the **$500 combined hold, burned, and sent threshold** that qualifies a wallet in the
first place. And once you are inside, your **allotment** - the cap on size and leverage for each prop
action - scales with lifetime OZ burned alongside your onchain trading record.
So burning is not purely destructive from your side of it. It converts supply into standing.
## What Burning Does to Supply
OZ has a fixed maximum of 100,000,000,000 and no minting path beyond it, so supply only moves in one
direction. As of July 28, 2026, **378,321,070 OZ** has been burned, which is 0.378 percent of supply.
How fast that number grows is up to holders. There is no emission schedule and no burn schedule,
because neither exists to promise.
## Related
- [OZ Token](/token/oz/)
- [Prop](/guides/prop-desk/)
---
# Troubleshooting
> Fixes for the problems people actually hit on Ozmium - reverted swaps, failed approvals, odd balances, black screens, and 402 loops on the agent API.
URL: https://docs.ozmium.org/guides/troubleshooting/
Markdown: https://docs.ozmium.org/guides/troubleshooting/index.md
Keywords: ozmium troubleshooting, transaction reverted base, insufficient allowance error, defi swap slippage revert, x402 402 loop
Updated: 2026-07-27
Most problems fall into a handful of categories. Work down this list before assuming something is
broken.
## Transaction Problems
**"Transaction reverted" on a swap.** Almost always slippage - the market moved past your tolerance
between quote and inclusion. Re-quote and retry, or widen slippage slightly on a thin pair. A revert
costs gas but does not cost principal.
**"Insufficient allowance".** The ERC-20 approval did not land, or it was for less than the action
needs. Approve again. On an injected wallet, approve and action are separate transactions and the
first can silently fail.
**"Insufficient funds for gas".** You spent the ETH you were holding for gas. Keep a small ETH buffer
that you never touch. Every transaction on Base needs it unless a host is sponsoring gas.
**Wrong network.** Ozmium is Base mainnet, chain id 8453, only. If your wallet is on another network,
switch it before anything will work.
**Position opened at a different size than expected.** Check whether you were reading a pending order
as a position. A resting limit or stop order holds collateral but has not filled. They are listed
separately for exactly this reason.
## Balance and Display Problems
**A balance looks wrong.** Check the transaction on [Basescan](https://basescan.org) first. The chain is authoritative and
every interface is downstream of it. If Basescan and Ozmium disagree, Basescan is right.
**A value is showing as unavailable rather than zero.** That is intentional. When a price feed or RPC
read fails, Ozmium keeps the last known-good value and marks it rather than rendering a confident
`$0.00` over a broken read. A fabricated zero in a finance app is worse than a blank.
**A token is missing.** Ozmium discovers tokens from onchain balances. A token with no liquid market
may show a balance without a confident USD valuation, which is correct behavior rather than an
error.
## App Loading Problems
**Black screen or a page that will not load.** The app carries a self-healing recovery path: if a
stale service worker is serving a dead cached bundle, it unregisters every worker, drops every cache,
and reloads once. If you land on a black screen anyway, a hard reload usually clears it. Clearing
site data for ozmium.org is the guaranteed fix.
**Stuck inside a host app.** Opened inside the [Base App](https://base.app/invite/ozbeta/D1H4FT25) or [Farcaster](https://farcaster.xyz/~/code/1914H5), the mini-app host controls the
webview. Close and reopen the mini-app rather than reloading inside it.
## Leverage-Specific
**Liquidated earlier than the displayed price.** The displayed liquidation price excludes rollover
and borrow fees. Those accrue continuously against your margin, so the real liquidation point drifts
closer on a position left alone.
**Stop loss filled worse than set.** In a fast move, the fill can be worse than the stop, or the
position can reach liquidation before the stop executes. A stop tells the venue when to act. The fill is decided by the market.
**Cannot decrease leverage.** Decreasing leverage requires a collateral top-up. Ozmium prepends the
USDC approve, but you still need the USDC.
## Agent-Specific
**Getting HTTP 402 repeatedly.** You are sending the payment header incorrectly, or the signed amount
does not match the challenge. Re-read the challenge in the `PAYMENT-REQUIRED` header and sign that
exact amount. See [x402 Payments](/agents/x402/).
**`bad payTxHash` or `bad burnTxHash`.** The x402 payment is not the authorization for a prop action.
You need a real onchain OZ transfer as well. See [Prop](/guides/prop-desk/).
**Rate limited.** Anonymous traffic has a far lower ceiling than paid traffic. Paying raises it
automatically; there is nothing to request.
**Transaction built by an endpoint reverts on broadcast.** Check that you have not modified the
returned `{ to, data, value }`, that the wallet you are broadcasting from is the wallet the builder
was given, and that any required approval landed first.
## A Market Order that Never Filled
Collateral escrowed against a market order the keeper never filled, usually one placed while that
venue was closed, is recoverable. Ozmium reads pending orders directly from the venue contract and
offers **Reclaim** once the execute timeout passes, which cancels the order onchain and returns the
collateral. Full detail in [Leverage](/guides/leverage/#reclaim-a-stranded-order).
## Reporting Something Broken
When something breaks, the app sends a diagnostic report so it can be fixed: the error, the page, the
app build, and basic browser details such as viewport and connection type. It records which **kind**
of wallet is connected - whether the browser has an injected provider at all - and never your wallet
address, your balance, or any identifier tied to you. Reports are grouped by error, not by person.
If you want a human to look at it, write to **[hello@ozmium.org](mailto:hello@ozmium.org)** or post
in the Discord. Either reaches the same place. Include what you were doing, the transaction hash if
there is one, and roughly when it happened.
The same two channels are where ideas go. If you want a market listed, an endpoint shaped differently,
a view that does not exist yet, or a workflow the app makes harder than it should be, say so. The
roadmap is built from what people ask for, and a specific request from someone actually using the
thing beats any amount of internal guessing.
{{discord}}
Security issues should go through the process in [Security and Trust](/company/security/) instead.
## Related
- [Install as an App](/start/web-apps/) - pinning Ozmium to a home screen, and what a stale build looks like
- [Charts](/guides/charts/) - reading the chart, its indicators, and its signal markers
