mallow API

Start Here

• Quickstart: read a listing, then build, sign and send a purchase, with TypeScript you can copy
• Errors: the error format, every status and code, and what is safe to retry
• SDKs and programs: the program clients, program addresses and token mints

API Versions

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

Authentication

Requests need 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].

Three reads need no key and can be called from any origin: marketplace fees, transaction fees and the staking overview.

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. The v1 send-draw endpoints do broadcast, but only draw transactions the buyer has already signed.

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. The quickstart has a retry helper.

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" } }

code is optional, and most errors don't carry one. A few failures aren't JSON at all. See Errors.

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, bidder, authority, …) rather than inferred from your API key.

Every builder except the Magic Eden buy accepts an optional targetPriorityFeeLamports to cap the priority fee. A few routes return more than one transaction, or a transaction that already carries a signature. Those are called out per endpoint and listed in the quickstart.

Gumball and Jellybean draws are the exception to "send it yourself": you sign them, and mallow co-signs and sends them. See Draws go through mallow.

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. On the account reads, a 404 means the address holds an account of another program or type. On the two buyer-stats reads, it means the listing or raffle does not exist. Use viewSlot to order a read against other reads of the same account.