# Souvenir

> Souvenir (souvenir.finance) is a Solana app where every coin is paired with a prize. Part of each trade's fee goes to the coin's prize pot. When the pot covers the prize, a round closes and one holder is drawn. Tickets come from a snapshot of holder balances, and the winning ticket from drand, a public random number anyone can check. Souvenir buys the prize and delivers it: an item shipped to the winner, or a skin, gift card or NFT sent to them. Some coins draw SOL instead of an item.

The reads and the MCP server below are public and read-only: no key, no sign-in, any origin.

## Coins and rounds over HTTP

Answers are JSON. SOL amounts are strings with nine decimals ("0.250000000"). Times are unix milliseconds. An error is {"error": {"code": "...", "message": "..."}}.

- GET /api/v2/coins: lists and searches coins. Query: q (a name, ticker, prize or the start of a mint), sort (pot, new, drawing or holders; pot by default), venue (pump, meteora or bags), nsfw (true to include coins whose prize is adult; they are left out by default, as on the site), limit (1 to 50, 20 by default), cursor (the last page's nextCursor). Answers {"coins": [...], "nextCursor": ...}; nextCursor is null on the last page. sort=drawing puts first the coins whose pot is nearest its target.
  curl "https://souvenir.finance/api/v2/coins?sort=drawing&limit=5"
- GET /api/v2/coins/{mint}: one coin: its mode, open pot, prize, current round, holders and links. The list's coins have the same shape. A coin is found by its mint whatever its prize.
  curl https://souvenir.finance/api/v2/coins/{mint}
- GET /api/v2/coins/{mint}/rounds: its rounds, newest first, 50 a page (cursor: the last page's next).
  curl https://souvenir.finance/api/v2/coins/{mint}/rounds
- GET /api/v2/coins/{mint}/rounds/{n}: one round with its proof: the snapshot slot, the ticket total, the Merkle root, the drand round and randomness, and the winning ticket.
  curl https://souvenir.finance/api/v2/coins/{mint}/rounds/1

## MCP server

https://souvenir.finance/mcp is a Model Context Protocol server (Streamable HTTP, stateless, no auth). Its four read-only tools answer what the routes above answer: search_coins, get_coin, get_rounds and get_round.

- Claude Code: claude mcp add --transport http souvenir https://souvenir.finance/mcp
- Other clients: add a remote MCP server with the URL https://souvenir.finance/mcp, or in a JSON config: {"mcpServers": {"souvenir": {"type": "http", "url": "https://souvenir.finance/mcp"}}}

## OpenAPI

- https://souvenir.finance/api/v2/openapi.json: the coin API above, and the writes a coin's creator makes with a coin key.
- https://souvenir.finance/api/v1/openapi.json: SouvSwap's shop API, which sells catalogue items for SOL or USDC.

## Limits

600 requests a minute per IP, shared by the HTTP reads and the MCP server. Past that, HTTP 429.

## More

- https://souvenir.finance/docs: how coins, pots, draws and claims work, in full.
- https://souvenir.finance/developers: the coin API, with an example for each route.