mallow API

The mallow API lets you access artwork listings, marketplace events, user data, and execute marketplace transactions programmatically.

API Versions

Both versions are served from the same base URL and use the same API key.

Authentication

All requests require an API key passed as a header:

x-api-key: YOUR_API_KEY

You can also pass the key as a query parameter: ?apiKey=YOUR_API_KEY

To get an API key, contact us in our Discord or at [email protected].

Try It in the Browser

Every endpoint page in this reference is live. Fill in the parameters, expand Authorization and paste your key into x-api-key, then hit Send to run the call against the real API and see the response inline.

Your key is remembered in your browser's local storage, so you only enter it once — every other endpoint page picks it up. It is never sent to this docs site: the request goes straight from your browser to https://api.mallow.art.

Calls made here are real, count against your rate limit, and are served by production. They cannot move assets or funds, though — the /v2/tx/* endpoints and the v1 get*Tx endpoints only build transactions. Nothing is signed or broadcast until you sign it yourself.

Rate Limits

API keys are limited to 100 requests per minute. Exceeding the limit returns 429 Too Many Requests; retry after the current minute window elapses.

Base URL

https://api.mallow.art

Pagination

Paginated endpoints accept page (0-indexed) and pageSize (max 30, default 30). Responses include nextPage (next page number if more results exist) and total (total count).

Response Envelope

All successful responses use a consistent envelope:

{ "result": <data> }

Paginated responses:

{ "result": [...], "nextPage": 1, "total": 100 }

Errors return:

{ "error": { "message": "human-readable message", "code": "MACHINE_READABLE_CODE" } }

Building Transactions

The /v2/tx/* endpoints return unsigned transactions — mallow never signs on your behalf and never broadcasts for you. Decode the base64 tx into a VersionedTransaction, sign it with the acting wallet, and send it yourself. The acting wallet is always named in the request body (buyer, seller, authority, caller, …) rather than inferred from your API key.

Every builder accepts an optional targetPriorityFeeLamports to override the compute-unit price. A few routes return more than one transaction, or return a transaction mallow has already co-signed — those are called out per endpoint.

Reading On-Chain State

The /v2 state reads wrap their payload alongside the RPC context slot the read was served at:

{ "result": { "viewSlot": 298134002, "account": <state> } }

An account that does not exist is a 200 with a null payload, not a 404 — a settled auction and an auction that was never created are indistinguishable on-chain. A 404 means the address decoded to the wrong program or account type. Use viewSlot to order a read against other reads of the same account.