Souvenir

A coin in prizes mode: gives winner an item, bought now from the coin's open pot at its fresh price plus a round's margin, as a round of the coin's: { round }. item is an id from search_prizes. The same idempotencyKey again answers the same round, whatever changed since. Refused when the pot is short, the item can't be bought now, or the winner is one of the coin's pools, Souvenir's wallets or its creator. Takes a coin key from create_coin_key as coinKey or as the request's Authorization: Bearer ck_live_… header; it works for every coin its wallet created. Refused with "The coin API's keys and writes are not open yet." while they are not open.

The trade's transaction for your wallet to sign, as the coin's page builds it: { transaction, out, minOut }, the transaction base64 (unsigned, version 0, paid by your wallet). It changes nothing until your wallet signs it and it is sent. Trading a coin, in order: (1) quote_trade to see what you would get; (2) build_trade with your wallet's address; (3) sign the transaction it answers with your wallet; (4) send_transaction, or send it yourself through any Solana RPC. No sign-in: your wallet's signature is the approval, and Souvenir never needs its private key. The same fees and limits as the coin's page on souvenir.finance.

Takes a won prize's SOL instead of the prize now, as the prizes page does, through the site's own route for that kind of prize: its share of the prize's worth (my_wins solOffer: 75% for a skin or a case, 66% for most others, 60% for a store's piece), or an xStocks prize's full worth. Paid to your wallet within minutes. Final: the prize can't be claimed after. Only while the win waits for you and only where the site offers it; hold to claim applies (your wallet must still hold 90% of the coins that counted for the win). Answers { ok } (and bps, the share). Takes the token from sign_in (sign_in_challenge with your wallet's address, sign its message with the wallet, sign_in), as token or as the request's Authorization: Bearer header. Refused with "Wins through the API are not open yet." while they are not open to your wallet, as launching is.

A coin key for the coins your wallet created, as the coin page's Developers dialog makes one: { key, id, webhookSecret, view }. The key (ck_live_…) and the webhook secret are shown this once: keep them. It works for set_coin_mode and award_prize and the coin API (souvenir.finance/api/v2/openapi.json), on every coin the wallet created. At most 5 live keys a wallet; revoke one with revoke_coin_key (or DELETE /api/v2/me/coinkeys/{id}, or on the coin's page). Only a coin's creator makes keys. Takes the token from sign_in, as token or as the request's Authorization: Bearer header. Refused with "Coin keys are not open yet." while the coin API's keys are not open.

One coin by its mint address, as search_coins lists it: mint, symbol, name, image, venue (pump, meteora or bags), origin (launched on Souvenir or brought), mode (full: its rounds draw an item; draws: they pay drawSol in SOL; prizes: its creator awards prizes), potSol (the open pot), prize (full mode: id, image, priceUsd), round (the latest unfinished one: number, state, targetSol, potSol), holders (at the latest snapshot) and links. A coin that is not on Souvenir is not found.

A coin's holders now, as its page shows them: { slot, total, streak, holdHours, holders }, the 50 with the most draw tickets: owner, amount (the coins held now, raw units), tickets, multiplier (1 to 2 with holding streaks, to 3 with staked coins), odds (of its next draw, 0 to 1) and locked (staked coins, raw) when there are any. Its pools, Souvenir's own wallets and the coin's creator are left out: they never win its draws. total is every ticket counted.

One round in full: { round } with its mode, target and pot, its state in words (stateText), and its proof: the holder snapshot's slot, the ticket total, the Merkle root, the drand round and randomness, and the winning ticket (SHA-256 of the randomness, as a number, modulo the total). A prize the creator awarded has proof { awardedBy: "creator" }; a round not drawn yet has none.

A coin's rounds, newest first, 50 a page. Answers { rounds, next }; each round: number, state, prize, winner, drawnAt, deliveredAt, paidSol (SOL paid to the winner, else null). For older rounds, pass next back as cursor; it is null on the last page.

What launching takes now for your wallet, as the site's launch form reads it: allowed and its reason, venues (meteora: Souvenir's own curve; pump: pump.fun), feeLevels and shareLevels in basis points, defaults, tickets (the ticket rules), holdHours, which prize kinds are open, basket, pump (pump.fun's fees; on BTC pairs its feeLevels, and shield and devBuy: whether the launch shield and a dev buy are open to you) and more. Takes the token from sign_in, as token or as the request's Authorization: Bearer header. Refused with "Launching through the API is not open yet." while it is not open to your wallet. Launching a coin, in order: (1) sign_in_challenge with your wallet's address, sign its message with that wallet, then sign_in for a token; (2) launch_options, and search_prizes for the prize; (3) prepare_launch; (4) sign the transaction it answers with your wallet, without sending it, and give it to submit_launch; (5) launch_status until it answers confirmed: a pump.fun launch first answers split with a second transaction, which you sign (or sign and send) and give to submit_split, then launch_status again. Your wallet pays and signs everything: Souvenir never needs or asks for its private key.

Where your launch stands, as the site's page follows it: { status, mint } with status pending (ask again in a few seconds), split (a pump.fun launch landed: transaction is the second approval, the split of its creator fee, for your wallet to sign; then submit_split), confirmed (the coin is on Souvenir) or failed (with reason). Takes the token from sign_in, as token or as the request's Authorization: Bearer header. Refused with "Launching through the API is not open yet." while it is not open to your wallet. Launching a coin, in order: (1) sign_in_challenge with your wallet's address, sign its message with that wallet, then sign_in for a token; (2) launch_options, and search_prizes for the prize; (3) prepare_launch; (4) sign the transaction it answers with your wallet, without sending it, and give it to submit_launch; (5) launch_status until it answers confirmed: a pump.fun launch first answers split with a second transaction, which you sign (or sign and send) and give to submit_split, then launch_status again. Your wallet pays and signs everything: Souvenir never needs or asks for its private key.

Your wallet's wins, as the site's prizes page reads them: { wins, link, evmAddress }, the newest first. Each win: mint, symbol, number (its round), skin (the prize), state (drawn: waiting for you; buying, sent, delivered; owed_sol, paid_sol; forfeited), stateText, linkDeadline (claim by then), keep (the coins you must still hold to claim, raw units), and its kind's details (goods, gift, stars, trip, stock, nft, evm, offer, pack). solOffer, when not null, is what claim_sol pays: bps of its worth, and lamports. An xStocks prize (stock) not claimed yet can be taken at its full worth in SOL. Every other claim (a shipping address, a gift card's code, a Steam trade link, a hotel) is on souvenir.finance/prizes. Takes the token from sign_in (sign_in_challenge with your wallet's address, sign its message with the wallet, sign_in), as token or as the request's Authorization: Bearer header. Refused with "Wins through the API are not open yet." while they are not open to your wallet, as launching is.

Prepares your launch, as the site's launch form does (the same checks, fees and rules): stores the picture and the coin's metadata and answers { mint, transaction, summary }, the transaction base64 for your wallet to sign (a pump.fun launch adds venue and transactions, the same one in a list). Sign it with your wallet without sending it and give it to submit_launch within the hour. The picture is imageUrl: an https address on a public host, fetched once, held to the site's picture rules (png, jpg, gif or webp, at most 4 MB). A coin with a prize names one: skin (an id from search_prizes), case, or basket (2 to 10 ids). With a dev buy your wallet's WBTC does not cover, it answers devSwap instead: sign its transaction and send it (send_transaction, or any Solana RPC), then prepare_launch again with devBuySats as given. Takes the token from sign_in, as token or as the request's Authorization: Bearer header. Refused with "Launching through the API is not open yet." while it is not open to your wallet. Launching a coin, in order: (1) sign_in_challenge with your wallet's address, sign its message with that wallet, then sign_in for a token; (2) launch_options, and search_prizes for the prize; (3) prepare_launch; (4) sign the transaction it answers with your wallet, without sending it, and give it to submit_launch; (5) launch_status until it answers confirmed: a pump.fun launch first answers split with a second transaction, which you sign (or sign and send) and give to submit_split, then launch_status again. Your wallet pays and signs everything: Souvenir never needs or asks for its private key.

What a buy or a sell of a Souvenir coin gives now, as the coin's page quotes it: { out, minOut, feeLamports, partial, venue }. out and minOut are the coin's raw units for a buy, lamports for a sell; minOut is the least you get at slippageBps. feeLamports is the trading fee (null on a pump.fun coin, where pump.fun takes it); partial, a buy larger than the curve has left (spent and refund say how much goes in). Trading a coin, in order: (1) quote_trade to see what you would get; (2) build_trade with your wallet's address; (3) sign the transaction it answers with your wallet; (4) send_transaction, or send it yourself through any Solana RPC. No sign-in: your wallet's signature is the approval, and Souvenir never needs its private key. The same fees and limits as the coin's page on souvenir.finance.

The latest wins on Souvenir, newest first, as the site's Recent winners lists them: { wins }, each with mint, symbol, coinImage, skin (the prize), skinImage, winner, winnerShort, round, at, state, ordered, claimRule, lastCall, solLamports (a last call's SOL), offer and worthUsd. Wins of adult (NSFW) prizes are left out, as on the site, unless nsfw is true: from the latest 200, so a page may hold fewer than limit.

Ends one of your coin keys now, as the coin page's Developers dialog does: { ok }. It is refused from then on and its webhook stops; it can't be made live again. id is the key's id, as create_coin_key answered it (GET /api/v2/me/coinkeys lists your keys with their ids). Works whatever the coin API's switch, so a leaked key can always be ended. 404 for an id that is not one of your live keys. Takes the token from sign_in, as token or as the request's Authorization: Bearer header.

Lists coins on Souvenir, searched and sorted. Answers { coins, nextCursor }. Each coin: mint, symbol, name, image, venue (pump, meteora or bags), origin (launched on Souvenir or brought), mode (full: its rounds draw an item; draws: they pay drawSol in SOL; prizes: its creator awards prizes), potSol (the open pot), prize (full mode: id, image, priceUsd), round (the latest unfinished one: number, state, targetSol, potSol), holders (at the latest snapshot) and links. For the next page, pass nextCursor back as cursor; it is null on the last page. Coins whose prize is adult (NSFW) are left out, as on the site, unless nsfw is true.

Prizes a coin can be launched with now, from Souvenir's catalogue: { prizes, total, next }. Each prize: id (what prepare_launch takes as skin), title, kind, priceUsd, from (true: a family priced from its smallest, which id names), image, and store, sizes or note when it has them. For the next page, pass next back as offset; it is null on the last page. No sign-in needed. CS2 skins are not listed here: a launch names one by its market name, such as "AK-47 | Redline (Field-Tested)". Launching a coin, in order: (1) sign_in_challenge with your wallet's address, sign its message with that wallet, then sign_in for a token; (2) launch_options, and search_prizes for the prize; (3) prepare_launch; (4) sign the transaction it answers with your wallet, without sending it, and give it to submit_launch; (5) launch_status until it answers confirmed: a pump.fun launch first answers split with a second transaction, which you sign (or sign and send) and give to submit_split, then launch_status again. Your wallet pays and signs everything: Souvenir never needs or asks for its private key.

Sends a transaction your wallet signed (base64, every signature in place) to Solana, as the site sends what a wallet signs: { signature }. Only one Souvenir built for you in the last few minutes (build_trade, or prepare_launch's devSwap), signed as it was built; any other is refused (not_built): send it through a Solana RPC. A trade can't be undone once it lands. With no answer from the network in time it may still land: its signature is answered the same. Trading a coin, in order: (1) quote_trade to see what you would get; (2) build_trade with your wallet's address; (3) sign the transaction it answers with your wallet; (4) send_transaction, or send it yourself through any Solana RPC. No sign-in: your wallet's signature is the approval, and Souvenir never needs its private key. The same fees and limits as the coin's page on souvenir.finance.

Your coin's mode from its next round (the round filling keeps its own): full (its rounds draw its prize), draws (each round pays drawSol in SOL to its winner) or prizes (you give prizes from its pot with award_prize). Answers the coin, as get_coin does. Takes a coin key from create_coin_key as coinKey or as the request's Authorization: Bearer ck_live_… header; it works for every coin its wallet created. Refused with "The coin API's keys and writes are not open yet." while they are not open.

The signed challenge: { token, wallet, expiresAt }, a token for an hour (then sign in again) that the launch tools take as token, or that the request sends as Authorization: Bearer <token>. Launching a coin, in order: (1) sign_in_challenge with your wallet's address, sign its message with that wallet, then sign_in for a token; (2) launch_options, and search_prizes for the prize; (3) prepare_launch; (4) sign the transaction it answers with your wallet, without sending it, and give it to submit_launch; (5) launch_status until it answers confirmed: a pump.fun launch first answers split with a second transaction, which you sign (or sign and send) and give to submit_split, then launch_status again. Your wallet pays and signs everything: Souvenir never needs or asks for its private key.

The first step of launching: { id, message, expiresAt } for your Solana wallet. Sign message (its UTF-8 bytes) with the wallet's ed25519 key and give id and the signature (base64) to sign_in within 5 minutes. Signing it authorizes no transaction or transfer. Launching a coin, in order: (1) sign_in_challenge with your wallet's address, sign its message with that wallet, then sign_in for a token; (2) launch_options, and search_prizes for the prize; (3) prepare_launch; (4) sign the transaction it answers with your wallet, without sending it, and give it to submit_launch; (5) launch_status until it answers confirmed: a pump.fun launch first answers split with a second transaction, which you sign (or sign and send) and give to submit_split, then launch_status again. Your wallet pays and signs everything: Souvenir never needs or asks for its private key.

Your wallet's signed launch: Souvenir checks it is the prepared one (your wallet may only add its compute budget or guard instructions), adds the coin's own signature and sends it. Answers { signature }. Then launch_status. Takes the token from sign_in, as token or as the request's Authorization: Bearer header. Refused with "Launching through the API is not open yet." while it is not open to your wallet. Launching a coin, in order: (1) sign_in_challenge with your wallet's address, sign its message with that wallet, then sign_in for a token; (2) launch_options, and search_prizes for the prize; (3) prepare_launch; (4) sign the transaction it answers with your wallet, without sending it, and give it to submit_launch; (5) launch_status until it answers confirmed: a pump.fun launch first answers split with a second transaction, which you sign (or sign and send) and give to submit_split, then launch_status again. Your wallet pays and signs everything: Souvenir never needs or asks for its private key.

The split launch_status handed over, approved by your wallet: either the signature of the transaction your wallet signed and sent itself, or the signed transaction (base64) for Souvenir to send. Answers { signature }. Then launch_status until confirmed. Takes the token from sign_in, as token or as the request's Authorization: Bearer header. Refused with "Launching through the API is not open yet." while it is not open to your wallet. Launching a coin, in order: (1) sign_in_challenge with your wallet's address, sign its message with that wallet, then sign_in for a token; (2) launch_options, and search_prizes for the prize; (3) prepare_launch; (4) sign the transaction it answers with your wallet, without sending it, and give it to submit_launch; (5) launch_status until it answers confirmed: a pump.fun launch first answers split with a second transaction, which you sign (or sign and send) and give to submit_split, then launch_status again. Your wallet pays and signs everything: Souvenir never needs or asks for its private key.