# opcode

> The opcode beta is live for trading tokenized stocks and ETFs with USDC on
> Ethereum mainnet. Email signup creates an embedded wallet, and users can add a
> passkey for return login. This file documents opcode's public, read-only
> market-data API.

Last updated: 2026-07-29. Every endpoint below is a public GET and needs no
authentication. Use the API from server-side clients or the same-origin app.
Cross-origin browser requests are not supported.

## Trade on opcode

Stock and ETF trades use USDC on Ethereum mainnet. Each quote shows what you
receive, the trading fee, and the settlement cost. The app tracks Ethereum
settlement and supports USDC withdrawals to an Ethereum address.

OPCODE trades in its own utility-token market. Holding OPCODE can qualify an
account for a lower trading-fee tier.

## The market catalog

`GET https://app.opcode.fi/api/catalog` returns the public market catalog, or a
filtered and projected slice, as
`{ "version": "...", "chain_id": 1, "assets": [ ... ] }`. `version` is a
content hash of the assets and changes when an immutable field or the row set changes.
Fields per asset:

- `symbol` - asset symbol, for example `NVDAon`
- `ticker` - clean exchange symbol, for example `NVDA`; omitted when unavailable
- `name`, `address`, `decimals`
- `sector` - nullable runtime metadata; examples include Technology, Energy, Financials, Healthcare, and Utilities
- `instrument_type` - nullable runtime metadata; examples include Stock, ETF, and Closed-End Fund (CEF)
- `archetype` - nullable; accepted values are `equity`, `fund`, `yield_wrapper`, `crypto`, and `cash`
- `issuer`, `category` - sparse metadata omitted when unavailable
- `index_tags`, `ticker_aliases`, `search_terms` - sparse metadata omitted when empty
- `tradable_sessions`, `available_ranges`

## Querying

Filter and project server-side with query params. All params are optional.
Filters are AND-combined across params. For the `sector`, `type`, `archetype`, and
`tag` facets, comma-separated values mean OR and matches are case-insensitive.
`q` is different: its entire value is one case-insensitive substring, not a
comma-OR list. `fields` returns only the keys you list. No params returns the
full catalog.

`v` is a cache hint for a catalog version the client already holds. On an
otherwise unfiltered request, `v` matching the current `version` returns the
catalog with `Cache-Control: public, max-age=31536000, immutable`. An absent or
stale `v`, or any filtered request, returns `Cache-Control: no-cache`.

```
# one sector, only the fields you need
curl "https://app.opcode.fi/api/catalog?sector=Technology&fields=ticker,name,address"

# a type, projected
curl "https://app.opcode.fi/api/catalog?type=ETF&fields=ticker,name,address"

# OR within a param, AND across params
curl "https://app.opcode.fi/api/catalog?sector=Technology,Energy&type=Stock&fields=ticker,name"

# a thematic tag
curl "https://app.opcode.fi/api/catalog?tag=gold&fields=ticker,name,address"

# free-text substring over symbol, name, ticker, and search_terms, capped
curl "https://app.opcode.fi/api/catalog?q=nvidia&limit=20&fields=ticker,name,address"

# by archetype
curl "https://app.opcode.fi/api/catalog?archetype=fund&fields=ticker,name,address"
```

Facets are `sector`, `type`, `archetype`, and `tag` (`index_tags` membership).
`type` accepts values such as Stock and ETF; CEF is the supported query alias for
Closed-End Fund (CEF). Accepted `archetype` values are `equity`, `fund`,
`yield_wrapper`, `crypto`, and `cash`. `q` is a single substring over symbol,
name, ticker, and `search_terms`. `fields` is any catalog field name. Unknown
facet values return an empty list; unknown field names are ignored; `limit` caps
the result.

To rank-match one name or ticker instead of filtering, use search, then fetch
that asset:

```
curl -s "https://app.opcode.fi/api/search?q=nvidia"
curl -s https://app.opcode.fi/api/instrument/<address>
```

For live prices, `GET /api/ticks` returns the catalog under `.catalog` plus a
per-address price map under `.ticks` (`price`, `change_24h_pct`, `volume_24h`,
`market_cap`).

## Endpoints

- [Market catalog](https://app.opcode.fi/api/catalog): full catalog or a filtered and projected slice
- [Markets and live prices](https://app.opcode.fi/api/ticks): catalog plus per-address price, volume, and market cap
- [Search](https://app.opcode.fi/api/search?q=): fuzzy match a name or ticker to addresses
- [Market open or closed](https://app.opcode.fi/api/market_status): session state and paused assets
- [Instrument detail](https://app.opcode.fi/api/instrument/{address}): per-asset detail by token address

## More

- [opcode marketing site](https://opcode.fi/)
- [opcode blog](https://opcode.fi/blog/)
- [opcode blog Atom feed](https://opcode.fi/blog/atom.xml)