# Agent API Overview
> Ozmium's AiFi API for autonomous AI agents - pay per call in USDC over x402, no account, no API key, no SDK. Live Base data and ready-to-sign calldata.
Source: https://docs.ozmium.org/agents/overview/
Keywords: aifi api, api for ai agents, defi api for autonomous agents, pay per call crypto api, ready to sign calldata, agent onchain transactions base
Updated: 2026-07-27
---

This is the AiFi half of the terminal: everything a human does in the Ozmium app, an agent can do
over HTTP. Your agent pays per call in
USDC over the x402 protocol and signs every transaction with its own wallet. Ozmium never custodies
funds or keys.

The whole design goal: **the shortest path from a question to a signed transaction on Base.**

## Why This Exists

Picture what an agent normally has to do before it can act onchain. It finds a price feed, then finds
a second one so it can tell whether the first is lying, then learns each protocol's parameter scaling,
gets the decimals right, encodes the approve, encodes the action, and finally discovers which of those
steps it got wrong by watching a transaction revert and paying for the privilege.

Ozmium sells the finished version of all that. Every endpoint hands back either the data you asked for
or a ready-to-sign `{ to, data, value }`, encoded against the exact Base mainnet contracts with the
parameter scales, decimals, and market ids already correct.

## No Account, No Key

There is no signup, no API key, and no key rotation. **Payment is authentication.** A valid x402
payment is the credential, and the wallet that paid is the identity.

Paid traffic is granted a far higher rate ceiling than anonymous traffic, automatically. There is
nothing to request and nobody to ask.

## Independently Scored

Cloudflare publishes [isitagentready.com](https://isitagentready.com), which grades a site on how
well an autonomous agent can discover, read, authenticate against, and transact with it.

**Ozmium scores 100 out of 100, at Level 5, Agent-Native.**

| Category | Score |
|---|---|
| Discoverability | 100, 4 of 4 |
| Content | 100, 1 of 1 |
| Bot Access Control | 100, 2 of 2 |
| API, Auth, MCP and Skill Discovery | 100, 7 of 7 |
| Commerce | 100, optional category |

That last row is the one worth noting. Commerce is an optional category on the rubric, because almost
nothing scored against it can actually take a machine payment. Ozmium can, through x402, which is why
the category is full rather than skipped.

Grade it yourself. The result is reproducible against the live site.

## Discovery Surface

Point your agent at any of these:

| Document | URL |
|---|---|
| Catalog and live prices (free, complete) | `https://ozmium.org/v1` |
| OpenAPI 3.1 with X-payment Pricing | `https://ozmium.org/v1/openapi.json` |
| MCP-shaped Tool Manifest | `https://ozmium.org/v1/tools.json` |
| MCP Server Card | `https://ozmium.org/.well-known/mcp/server-card.json` |
| x402 Discovery | `https://ozmium.org/.well-known/x402` |
| ACP Descriptor | `https://ozmium.org/.well-known/acp.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` |
| Human-readable Auth Guide | `https://ozmium.org/auth.md` |
| Full Plain-text Reference | `https://ozmium.org/llms-full.txt` |

The catalog at `/v1` is free and complete. Start there.

## Found Us Through A Marketplace?

Ozmium is listed on **[Agentic Market](https://agentic.market/services/ozmium-org)** as *Ozmium Agent
API*. Agentic Market is a directory of x402-enabled services - operated by Coinbase, owned by the
Linux Foundation - where agents browse and call services with per-request USDC pricing and no
registration or API keys.

The listing carries the whole `/v1` surface: prices, crowd positioning, signals, candles, portfolio
and position reads, vault and loan markets, ranked ideas, arbitrage, and every transaction builder
from swaps through [Morpho Midnight](https://docs.morpho.org) fixed-rate borrowing and Gains perpetual management.

If your agent discovered Ozmium there, nothing changes about how you call it - the endpoints, the 402
flow, and the pricing are the same ones documented here, because they are the same service. The
directory is a front door, not a middleman, and no request is proxied through it.

:::note Prices come from the challenge, not the listing
A marketplace entry is a snapshot. The authoritative price for any endpoint is always the one in its
own 402 challenge, and prepaid OZ credit halves it. If a directory shows you something different,
trust the challenge.
:::

## What You Can Buy

| Tier | Price per Call | Endpoints |
|---|---|---|
| Data | $0.001 | Prices, crowd positioning, signals, candles, swap quotes, portfolio, positions, pending orders, history, stats, vaults, loan markets, pair universe |
| Focused Alpha | $0.005 | Single-symbol chart read, two-asset comparison, prop quote |
| Strict Ideas | $0.008 | The highest-conviction shortlist only, one per direction per category |
| Alpha | $0.01 | Ranked ideas, arbitrage, cross-asset scan, loan risk analysis |
| Actions and Bundles | $0.01 | Every transaction builder, the full alpha bundle, market-wide summary, the loose idea field, prop execute |

At rest nothing costs more than a penny. Prices can surge during congestion, but the surge is **capped
at 2x**, so a hot window tops out at two.

**Prepaid OZ credit pays half of every price above and is exempt from surge entirely**, which makes it
the cheapest way to call this API. See [OZ credit](/agents/x402/#paying-in-oz-the-credit-rail).

The authoritative price for any endpoint is always the one in its own 402 challenge. Do not hardcode
these.

Full listing: [Endpoint Catalog](/agents/endpoints/).

## The Trust Model

Non-custodial, permanently:

- Ozmium never holds funds or keys.
- Ozmium never signs on your behalf.
- Every action is calldata you inspect and broadcast yourself.
- The chain enforces the outcome.

Nothing sold here locks anyone out of anything. Morpho, Aave, Gains, [Aerodrome](https://aerodrome.finance), and Uniswap remain
directly usable forever, for free, without us. What Ozmium sells is correctness, convenience, and
speed for AI agents.

## Referrals: 20 Percent

Append `?ref=<your-wallet>` to any `/v1` endpoint or app URL you share. **You earn 20 percent of the
paid x402 volume from wallets you refer.** `GET /v1/referrals/{wallet}` is free and returns your
tally and the amount owed.

Every 402 challenge ships a `promote` kit at the top level of the challenge JSON - a sibling of
`accepts` and `extensions`, not inside `extensions` - so recruitment costs you no tokens to compose:

- `pitch` - a ready-to-post pitch string carrying your referral link
- `shareUrl` - the app URL with your ref parameter
- `referralParam` - the raw `?ref=<your-wallet>` to append anywhere
- `baseAppInvite` and `onboarding` - for humans who need a Base account first
- `discovery`, `openapi`, `catalog` - machine-readable entry points to hand another agent

Pass your own `?ref=` on the call and every string comes back with your address already substituted,
ready to post verbatim. Call without it and you get a `<your-wallet>` placeholder to fill in.

## Marker Feed Disclosure

:::warning Marker feeds are unproven
The `/v1/ta` and `/v1/ta/scan` marker feeds 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. Leverage can liquidate you; that is the chain's arithmetic, not
our opinion.
:::

## FAQ

### Do I need an API key to use the Ozmium API?

No. There is no signup, no API key, and no key rotation. Payment is authentication: a valid x402
payment is the credential and the wallet that paid is the identity.

### How much does the Ozmium agent API cost?

From $0.001 per call for data reads to $0.01 for transaction builders, settled in USDC on Base.
Congestion surge is capped at 2x, and prepaid OZ credit pays half of every price with no surge at all.
Read the amount from the 402 challenge rather than hardcoding it.

### What does a transaction builder return?

A ready-to-sign `{ to, data, value }` encoded against the exact Base mainnet contracts, with
parameter scales, decimals, and market ids already correct. Your agent broadcasts it from its own
wallet. Ozmium never signs.

### Can an agent open a leveraged position through Ozmium?

Yes. `POST /v1/tx/risk/open` returns calldata for a Gains [gTrade](https://gains.trade) perpetual with USDC collateral, with
gTrade's exact scaling handled. `modify` and `close` complete the lifecycle.

### Does Ozmium hold an agent's funds?

Never. Ozmium is non-custodial for AI agents exactly as it is for people. Every action is calldata the
agent inspects and broadcasts itself, and the chain enforces the outcome.

### How do agent referrals pay out?

Append `?ref=<your-wallet>` to any `/v1` endpoint or shared app URL. You earn 20 percent of the paid
x402 volume from wallets you refer. `GET /v1/referrals/{wallet}` is free and returns your tally and
the amount owed.

### Is there an MCP server for Ozmium?

Ozmium publishes an MCP-shaped tool manifest at `/v1/tools.json` and an MCP server card at
`/.well-known/mcp/server-card.json`, so agent frameworks can discover its endpoints as tools.

### Where can agents discover Ozmium?

Directly through the free catalog at `/v1`, through the OpenAPI, MCP, ACP, and x402 discovery
documents, or through the Agentic Market directory, where Ozmium is listed as
[Ozmium Agent API](https://agentic.market/services/ozmium-org). All of them point at the same
endpoints on the same service.

## Next

- [x402 Payments](/agents/x402/) - the exact request flow
- [Endpoint Catalog](/agents/endpoints/) - every endpoint and its price
- [Integration Notes](/agents/integration/) - the mistakes worth avoiding