# Ozmium - Base Mainnet DeFi For AI Agents (Full Reference)

> Trade. Accumulate. Leverage. Non-custodial DeFi on Base mainnet (eip155:8453) with a paid
> machine API built for autonomous agents: live market data plus ready-to-sign transaction
> calldata for swaps, yield vaults, collateralized loans, and leveraged perpetuals. Your agent
> pays per call in USDC over x402 (no account, no API key) and signs every transaction with its
> OWN wallet. Ozmium never custodies funds or keys; the chain enforces every action.

This is the expanded reference. The concise index is at https://ozmium.org/llms.txt.

## Base URL And Discovery

- Base: https://ozmium.org/v1
- Catalog + live prices (free): GET https://ozmium.org/v1
- OpenAPI 3.1 (with x-x402 pricing): https://ozmium.org/v1/openapi.json
- MCP-shaped tool manifest: https://ozmium.org/v1/tools.json
- x402 discovery: https://ozmium.org/.well-known/x402
- MCP server card: https://ozmium.org/.well-known/mcp/server-card.json
- Agent skills index: https://ozmium.org/.well-known/agent-skills/index.json
- API catalog (RFC 9727): https://ozmium.org/.well-known/api-catalog
- Auth model (RFC 9728): https://ozmium.org/.well-known/oauth-protected-resource

## Payment (x402 v2, exact-EVM, EIP-3009 USDC on Base)

1. GET or POST any /v1 endpoint. An unpaid call returns HTTP 402 with a PAYMENT-REQUIRED header
   describing the amount, the USDC asset (Base mainnet), and the pay-to address.
2. Sign the EIP-3009 transferWithAuthorization for that amount with your wallet. Any x402 client
   library (for example the @x402 packages) builds and signs this for you.
3. Retry with the PAYMENT-SIGNATURE header. You get 200 + the data (or the built transaction) and
   an on-chain settlement receipt. No account, no API key, no subscription.

Pricing (USDC per call, may surge during network congestion):
- Data reads: $0.001
- Premium alpha (/v1/arbitrage, /v1/ideas): $0.01
- Alpha bundle (/v1/alpha): $0.02
- Transaction builders (/v1/tx/*): $0.02

## Data Endpoints ($0.001/call)

- GET /v1/prices?symbols=BTC,ETH,SOL -> spot USD price + 24h change per symbol.
- GET /v1/signals?symbol=BTC -> multi-indicator TA bundle (RSI, MACD, Bollinger, VWAP, trend,
  candlestick pattern) reduced to a directional bias + conviction score.
- GET /v1/candles?symbol=BTC&tf=1h -> OHLCV series for the timeframe.
- GET /v1/swap/price?from=USDC&to=cbBTC&amount=100 -> expected output + route + fees.
- GET /v1/portfolio/{address} -> token balances + USD valuation for a wallet.
- GET /v1/positions/{address} -> open leveraged perp positions (size, leverage, liq price, PnL).
- GET /v1/history/{address} -> closed-trade ledger (entry, exit, reason: TP / SL / LIQ).
- GET /v1/stats/{address} -> win rate, expectancy, profit factor scorecard.
- GET /v1/earn/vaults -> Morpho + Aave vault list with live APY.
- GET /v1/loan/markets -> collateral markets with LTV, borrow APY, available liquidity.
- GET /v1/risk/pairs -> tradeable Gains gTrade pairs (pairIndex, max leverage, spread).

## Alpha Endpoints

- GET /v1/arbitrage?target=cbBTC&budget=100&taker=0x... ($0.01) -> ranked, FEE-NETTED cross-asset
  and DEX-vs-Coinbase arbitrage routes into the target; each route is executable via /v1/tx/swap.
- GET /v1/ideas?limit=6 ($0.01) -> ranked scalp long/short setups across the pair universe, each
  with entry, stop, range-survival leverage, and pairIndex; executable via /v1/tx/risk/open.
- GET /v1/alpha ($0.02) -> arbitrage + ideas + signals combined in one call.

## Transaction Builders ($0.02/call, return ready-to-sign { to, data, value })

- POST /v1/tx/swap -> spot swap on Base.
- POST /v1/tx/send -> transfer a token or ETH.
- POST /v1/tx/tip -> fund the Ozmium prop desk (no return promised).
- POST /v1/tx/earn/deposit, /v1/tx/earn/withdraw -> Morpho vault supply / redeem.
- POST /v1/tx/earn/aave/supply, /v1/tx/earn/aave/withdraw -> Aave supply / withdraw.
- POST /v1/tx/loan/supply-collateral, /v1/tx/loan/borrow, /v1/tx/loan/repay,
  /v1/tx/loan/withdraw-collateral -> collateralized USDC borrowing lifecycle.
- POST /v1/tx/risk/open, /v1/tx/risk/close, /v1/tx/risk/modify -> Gains gTrade leveraged perps
  (USDC collateral, up to 200x). Builders return correct contracts, parameter scales, and market
  ids on Base mainnet - the details agents most often get wrong when integrating raw.
- POST /v1/tx/burn -> burn OZ (send to the dead address) to rank on the on-chain burn ladder.

Every builder returns exact calldata; you broadcast from your own wallet. Ozmium never signs.

## Referrals (earn by referring other agents and humans)

Append ?ref=<your-wallet> to any /v1 link or the app URL and share it. Paid x402 volume from
wallets you refer is credited to you. GET /v1/referrals/{wallet} returns your tally. Every /v1
response carries a `promote` kit so your agent can recruit other agents in one step.

## OZ Token

OZ on Base: 0x148313dcdb7a7111ebefa4871f6a7fef34833b07 (18 decimals, 100B supply, burn-preferred).
Acquire OZ via /v1/tx/swap from any liquid input token. Burning OZ ranks wallets on the burn ladder.

## For Humans

The web app at https://ozmium.org is free for people; this paid API exists only for automated
clients. Nothing sold here locks anyone out: Morpho, Aave, and Gains are always usable directly.
Ozmium sells correctness, convenience, and speed for machines - the executable calldata, the
fee-netted routes, and the ranked setups an agent would otherwise assemble itself.