Marketplace API
The Marketplace / Trading REST API: base URL, bearer auth, and the known resources (tokens, token detail, candles). Evolving; OpenAPI forthcoming.
The Marketplace / Trading API is Assetera's browser- and partner-facing REST API. It is a resource server that validates standards-based OIDC / OAuth 2.0 access tokens against JWKS. Resolve its base URL from the marketplace API per environment rather than hardcoding a host.
This API is an early "learning slice": deliberately small, the starter the full marketplace API grows from. A machine-readable OpenAPI / Swagger document is not yet published. When it ships it becomes the authoritative contract and this page will link to it.
Authentication
Every non-public endpoint requires a bearer token:
Authorization: Bearer <access_token>The service validates the token's signature, issuer, and audience against the provider's JWKS, then
reads the signed tenant claim and scopes every query to that tenant. Write operations additionally
require the marketplace-admin role. See Authentication for how to obtain a
token.
Resources
The API today centres on a thin tokens resource (a listing an admin creates and edits and a consumer
reads) plus a market-data stub for chart candles.
WIP, updated during marketplace-api development
| Method | Path | Access | Notes |
|---|---|---|---|
GET | /healthz | Public | Liveness probe; no auth. |
GET | /tokens | Authenticated | List listings, tenant-scoped. Cursor-paginated and filterable (see below). |
GET | /tokens/:id | Authenticated | A single listing by id. |
POST | /tokens | marketplace-admin | Create a listing. |
PUT | /tokens/:id | marketplace-admin | Update a listing. |
DELETE | /tokens/:id | marketplace-admin | Remove a listing. |
GET | /tokens/:id/candles | Authenticated | OHLC candles for a listing. Stub (see below). |
Candles are a stub seam. GET /tokens/:id/candles returns mock OHLC data today. Real chart data is
greenfield and will be served by a dedicated market-data / indexer service (ingest trades, aggregate OHLC,
serve). It sits behind a stable contract, so code against the endpoint shape now and it keeps working when
real data lands.
Pagination, filtering & search
GET /tokens returns a cursor-paginated page, not the whole catalog. This matters: partner catalogs run
to thousands of listings, so always page and filter rather than fetching everything.
| Query param | Purpose |
|---|---|
limit, cursor | Page size and the opaque cursor for the next page |
status | Filter by lifecycle status (active, paused, ...) |
chain | Filter by CAIP-2 chain id (for example eip155:137) |
source | Filter by catalog source (for example legacy-monolith, ondo) |
symbol, name | Search by ticker or name |
Consumer reads return only listings entitled to your tenant with status active or paused and not
hidden. A marketplace-admin cross-tenant read returns everything, including deleted, which is the
audit/archive surface. See Tokens & pairs for the lifecycle and field
model.
Example: list listings
Fetch the first page of tenant-scoped listings. Resolve the host from the marketplace API and substitute a real access token for the placeholder.
GET /tokens?status=active&limit=20 HTTP/1.1
Host: api.<base_domain>
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.<PLACEHOLDER_TOKEN>
Accept: application/json{
"items": [
{
"id": "tok_01H...",
"source": "legacy-monolith",
"symbol": "ASST-A",
"name": "Sample Asset A",
"base_asset": "ASST",
"quote_currency": "USDC",
"chain_id": "eip155:137",
"token_ref": "0xabc...def",
"min_price": "0.95",
"max_price": "1.05",
"status": "active"
}
],
"next_cursor": "eyJpZCI6IuKApiJ9"
}WIP, updated during marketplace-api development
The response shape above is provisional. Field names are modelled on the catalog design, not a
published contract, and several fields are nullable (base_asset, quote_currency, chain_id,
min_price / max_price). Do not hardcode field names yet; the authoritative shape lands with the OpenAPI
document.
A missing or invalid token yields 401; a token without the required role on a write yields 403; a listing
outside your tenant is simply not visible.
Stability and what's next
- The shape will grow. The current surface models a listing; balances and real chart data are intentionally out of this slice for now.
- OpenAPI is forthcoming. When published it becomes the authoritative contract and this page links to it.
- Multi-tenant from day one. Your token's
tenantclaim, not any parameter, decides what you see.
See also: Authentication · Compliance API · Real-time (SSE).
Authentication (Keycloak)
What credentials a tenant receives, how to use them, and what they represent. Assetera Identity is a Keycloak realm speaking standard OIDC / OAuth 2.0.
Compliance API
The API an integrator or back-office reads server-side to get a user's KYC / compliance status. Assetera is the responsible party for KYC/AML. Mostly planned.