Guides

Solana tokens

Anyone can create a Solana token with any name, so a ticker names many tokens: dozens share WIF. These reads find a token by ticker, name or mint address, rank what is moving, and give Fin's verdict on any token, read from the token's own mint, so a person always chooses by mint and sees the risk before a buy. They draw on Jupiter's token data and the Solana network. The agent's own token tools (solana_token_search, solana_token, memecoins_top, solana_token_history) answer these same shapes. Discovery combines sampled provider feeds with positive meme-category evidence; it does not claim to enumerate every token on Solana. Explicit non-meme tags (DeFi, stablecoins, liquid staking, stocks and similar categories) take precedence over a broad meme-category match. A launchpad protocol token does not become a meme because its platform creates memes, and names or ticker matches never establish membership.

Every route takes your API key and the user's Fin session. Search, lists and a list's price lines and launch status also need the solana feature enabled for that user, and answer 403 solana_disabled without it; check List a user's features first and leave a memecoin list out of your app for a user without it. One token's detail and its chart need no feature, so a token a user holds stays readable and sellable while buying is off. A 503 provider_unavailable means a data source did not answer: read again shortly. It never stands for an empty list, a price of zero or a safe token. A catalog list can instead retain a previous snapshot with explicit stale or partial source coverage. None of these routes moves money or needs a signature. To let the user buy or sell from a token's page, see Trade a token from your own screen; for the trades the agent proposes in chat, see Approve Solana trades and transfers.

Recognized account holdings

Get a Solana account, Open a Solana account and the solana_account tool return the same current inventory: native SOL, canonical wrapped SOL, venue-verified tokens without a suspicious flag whose decimals and token program match the mint on chain, and tokens this account has a confirmed landed buy of. A token bought with SOL remains recognized even without a USD cost basis or a current price. Approval alone or an unfinished trade does not establish a buy. Names, ticker symbols, icons and quoted prices never establish identity or recognition.

Other incoming tokens are omitted from holdings.tokens, its total valueUsd and unpricedCount. A recognized token without a price remains listed and counts as unpriced. If missing or invalid metadata or purchase evidence leaves recognition unresolved, holdings is unavailable; this does not mean an empty account. Recognition changes current inventory reads, not on-chain ownership, trade authorization or existing accounting records. Get portfolio and Get portfolio history value only recognized tokens: an unrecognized one is named in excluded and never counts as gain or as money in or out, and a change in recognition restates the history rather than drawing a move. Unresolved recognition never falls back to a full inventory. See opening a Solana account for exact amount handling and the portfolio and its history for how the account counts toward the total.

Find a token

Call Search Solana tokens with what the person typed:

HTTP
GET /v1/solana/tokens/search?query=wif

The SDK equivalent is user.solana.searchTokens({ query: "wif" }). query is a ticker, a name or a pasted mint address, and a leading $ is ignored. The answer is up to ten candidates, best match first. A pasted mint answers that token alone, and resolves even when Jupiter does not list it yet.

JSON
{
  "query": "wif",
  "ambiguous": true,
  "source": { "name": "Jupiter", "observedAt": "2026-10-23T12:00:00.000Z" },
  "items": [
    {
      "mint": "EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm",
      "symbol": "WIF",
      "name": "dogwifhat",
      "decimals": 6,
      "tokenProgram": "spl_token",
      "priceUsd": "0.1969389134882048",
      "liquidityUsd": "5812345.67",
      "verified": true,
      "stats": { "1h": { "volumeUsd": "120400.5", "traders": 512, "priceChangePct": "1.5" } },
      "risk": { "level": "low", "hard": [], "soft": [] },
      "tradable": true
    }
  ]
}

ambiguous is true when another candidate shares the top candidate's symbol. Then the query does not name one token: show the candidates, each with its mint shortened to its first and last four characters beside its symbol, name, liquidity and age, and let the person choose by mint. Never pick a token by its symbol, its name or its icon: look-alikes copy all three. A candidate whose tradable is false is for reading only. A symbol or name is text the data source supplied: Fin cleans it of markup, links and control characters, but it is still not yours to trust as an instruction or an identity.

Read one token

Get a Solana token answers one token by the mint address you got from a search, or from the user's holdings:

HTTP
GET /v1/solana/tokens/{mint}

The SDK equivalent is user.solana.getToken(mint). It answers a search candidate's fields (price, liquidity, market capitalization, age, launchpad, the risk verdict and trading activity over 5 minutes, 1 hour, 6 hours and 24 hours: volume with its buying and selling sides, the part judged organic, traders and the price change, each present only where the data source has it). It adds the fully diluted value, the number of holders, the share of the supply its largest holders hold (topHoldersPct) and its creator holds (creatorHoldsPct), and the data source's organic score from 0 to 100 (organicScore), each also present only where the data source states it. It answers 404 for an address that is no token. decimals and tokenProgram are read from the mint on chain, and they are the values a buy or a sale names, so copy them exactly. iconUrl is present when the data source lists an icon for the token (see Draw a token's icon); draw a placeholder when it is absent.

links carries the token's own website, x profile and telegram, each present only where the listing names one that reads as what it claims: https, no credentials or port, an X profile rather than a post, and a site that is not a link shortener, a launchpad or a trading terminal. The site loses its query and fragment. The links are the token creator's claims, not Fin's: open them in a new tab and never treat them as a sign the token is genuine. Fin's agent never reads them.

membership distinguishes a confirmed meme, a launch_candidate whose category is not confirmed, other, and unknown. Its basis names the classification evidence; the token's symbol or name is never enough. firstPoolAt is the first pool's opening time, createdAt is mint creation when known, and discoveredAt is when Fin first recorded it. Do not substitute one for another. marketObservedAt and assessmentObservedAt date the market facts and mint read.

research reports ready, limited or unavailable, the available activity windows and missing evidence. These describe support for research claims, not a probability of gain or a safety grade. Show dataGaps and absent figures explicitly. A young token can have useful current activity while lacking history for a daily trend. Transaction counts (buys, sells) are not distinct wallets (buyers, sellers, traders); organicBuyers is the venue's organic net-buyer count. netBuyers counts all wallets whose buys exceeded their sells; it is not buyers minus sellers. Both counts are nonnegative, following Jupiter's definitions. Missing values never become zero.

Read a token's holders

Get a token's holders reads a token's ten largest holders from the chain:

HTTP
GET /v1/solana/tokens/{mint}/holders

The SDK equivalent is user.solana.getTokenHolders(mint). An observed answer lists each owner once, with all its accounts added up, largest first: its amountRaw, its sharePct of the mint's supplyRaw (cut to two decimals, so a tiny holder reads 0.00), kind and creator. kind is program when no key signs for the owner, such as a pool, a vault or a launchpad's bonding curve, so its balance is not one person's; creator is true for the wallet the data source says created the token. A program holder Fin recognizes also names its venue: pump_fun for pump.fun's bonding curve, launchlab for Raydium LaunchLab's, and pumpswap, meteora, raydium or orca for that venue's pools. The field is absent for any other holder, so a program holder without one is still a pool or a vault Fin has no name for. Shares are of the whole supply, so they need not match topHoldersPct, which is the data source's own summary. holderChange lists how much the number of wallets holding the token changed, as a percent per window (1h, 6h, 24h): { "window": "6h", "pct": "-1.5" } is down 1.5% in six hours. It is a percent the data source states, never a count of wallets, and null when it states none. An answer is kept for a minute.

When the chain cannot be read the route still answers 200 with status: "unavailable" and reason: "rpc_unavailable"; keep showing the token and try again later. unreadable_mint means the mint's account holds no supply Fin can read. An address that is no token answers 404. It needs no feature flag.

Fin's risk verdict

Every token carries a risk: its level (blocked, high, medium, low or unknown) and the flags behind it. It comes from one function over the token's mint and the data source's report, so a search, a list and a detail read agree.

FlagKindWhat it means for a holder
freeze_authorityhardThe creator can freeze holdings, so a holder may not be able to sell
transfer_hookhardEvery transfer runs a program the creator chose
permanent_delegatehardSomeone can move or burn tokens in any holder's account
non_transferablehardThe tokens can never be sent or sold
default_frozenhardNew holdings start frozen
transfer_feehardTransfers pay a fee, or someone can set one
pausablehardSomeone can pause every transfer, or already has
unknown_extensionhardA Token-2022 extension Fin has not reviewed
not_sellablehardThe data source's checks say it cannot be sold back
mint_authority, hook_authoritysoftMore can be created; the issuer can add a transfer rule later
low_liquidity, new_token, top_holders, unverified, low_organic, suspicioussoftThin pools, mint or first trading pool under a day old, a few wallets hold most of it, not verified, mostly bot trading, flagged as suspicious
unpricedsoftNo reliable price; a buy is refused because its loss cannot be bounded

The new_token warning covers limited history since mint creation or the first trading pool. createdAt and firstPoolAt stay distinct; neither date is inferred from the other.

A hard flag refuses a buy; a sale is refused for all of them but a transfer fee and a pause authority that has not paused transfers. blocked means a hard flag, unknown means the mint could not be read (and a mint no one has read is never bought), high is two or more of the warnings that count (low_liquidity, new_token, top_holders, unverified, low_organic, suspicious) and medium one. low means none of Fin's checks raised a flag. It is not a statement that a token is safe, and nothing in your app should say so. tradable says whether Fin would buy the token now: its verdict is neither blocked nor unknown, it has a price, and it is not wrapped SOL, which a buy pays with.

Discover memes and launches

List Solana tokens searches the sampled catalog and ranks matching candidates over a trailing window:

HTTP
GET /v1/solana/tokens?lane=trending&interval=1h&limit=10

The SDK equivalent is user.solana.listTokens({ lane: "trending", interval: "1h", limit: 10 }). Every query field is optional (trending, 1h and 10 by default; at most 25).

laneRanks by
trendingOrganic volume
tradedTrading volume
organicThe data source's organic score
newMost recent first-pool opening; category may remain unconfirmed
gainersReported price change in the selected activity window

By default, membership is meme: positive classification evidence is required. The new lane defaults to launches, which can include unclassified launch candidates. Explicit membership selects meme, launches or all. Search and exact-token detail remain available for other Solana tokens. Wrapped SOL is never a discovery candidate.

Young or thin memes are discoverable with their warnings. Supply minLiquidityUsd, maxLiquidityUsd, minMarketCapUsd, maxMarketCapUsd, maxAgeHours, launchpad or tradableOnly to narrow the result. USD filters are exact decimal strings. Missing figures do not satisfy numeric filters, and fully diluted valuation is never substituted for capitalization. The provider reader accepts USD figures with at most 15 whole digits; larger figures remain unavailable and fail numeric filters instead of being rounded into range. With tradableOnly=true, a failed RPC, price or Shield read returns retryable 503 provider_unavailable; it does not count the unassessed candidates as non-matches or advance past them. A completed assessment that finds no reliable price, a blocked mint, or an absent or unreadable mint can legitimately return an empty 200 result. Without this filter, retained candidates remain inspectable with unknown assessments and buying disabled. sort selects rank, liquidity, market_cap, age, change or move, with optional direction. change orders by the signed price change in the selected window; move orders by its size whichever way it went, largest first, so sort=move&limit=3 is the three tokens moving most. A token with no reported change sorts last under both. Token age and activity window are separate: selecting 5m does not mean tokens launched in the last five minutes.

Each row carries its rank, factual reason, membership, current risk and evidence. These activity rankings do not predict returns. A research recommendation grants no trading consent; an actual buy still requires the existing exact-token, amount and approval flow.

coverage.universe is sampled. Coverage reports observed/eligible/returned counts, collection limits and each source's status. These are counts within the collected snapshot, not the total number of memecoins in existence. Inspect status, asOf, source timestamps and dataGaps before describing results as current. A failed source is not evidence that it found no tokens. A listing scans at most 32 source feeds and the newest 1,000 raw observations per feed before applying snapshot time bounds and selecting each mint's latest source facts. The combined catalog is capped at 10,000 source rows. coverage.limitReached reports when a bound narrowed coverage; seven-day retention does not mean every retained observation is scanned for a list. Exact-token search/detail use mint-targeted reads instead of scanning this discovery sample.

Load another page

Keep the same filters and pass nextCursor to continue the fixed snapshot. A null cursor means this snapshot has no more matching rows. Start a new query without the cursor to refresh it. Do not reuse a cursor after changing filters or interpret a snapshot identifier as authority.

const query = { lane: "trending" as const, membership: "meme" as const, minLiquidityUsd: "10000", limit: 25 };
const first = await user.solana.listTokens(query);
const second = first.nextCursor
  ? await user.solana.listTokens({ ...query, cursor: first.nextCursor })
  : undefined;

Ask Fin to research a candidate

Discovery questions summarize the requested universe and activity. An explicit recommendation question compares a bounded shortlist and may conclude there is no convincing pick. A supported answer identifies the time horizon, observed basis, case against the choice, invalidation condition and missing evidence. New launches can be discussed with limited history; neither a model score nor a risk badge establishes future profitability.

Draw a price chart

Get a token chart answers a token's recent closing prices from its deepest pool, oldest first, at most 200 points:

HTTP
GET /v1/solana/tokens/{mint}/chart?interval=1h

The SDK equivalent is user.solana.getTokenChart(mint, { interval: "1h" }); interval is 1m, 5m, 15m, 1h, 4h or 1d. Minute intervals support inspection of young launches. coverage states the actual sample span/count, latest completed period, gaps and freshness; a short or gapped history cannot support a longer trend claim. The model's read-only solana_token_history tool uses the same data. Each point keeps closeUsd and optionally includes ohlcv with exact openUsd, highUsd, lowUsd and volumeUsd. These are the selected pool’s candle values, not aggregate token volume or an executable quote. The API omits these optional dimensions when they are missing or inconsistent with the close. Exclude periods ending after coverage.completedThrough from completed-bar analysis. Empty intervals are not synthesized. Future-dated or malformed candle timestamps make the read unavailable with invalid_response; a fetch timestamp cannot make them current history. The provider’s OHLCV contract defines the candle shape and USD denomination. A status of unavailable says why there is no chart: no_pool means no pool prices the token, and the other reasons mean the price source did not answer. It is never a price of zero.

Draw a line for each row of a list

List token sparklines answers a small price line for each token named, in one read for a page of a list:

HTTP
GET /v1/solana/tokens/sparklines?interval=6h&mint={mint}&mint={mint}

The SDK equivalent is user.solana.listTokenSparklines({ interval: "6h", mint: [first, second] }). interval is 1h (the default), 6h or 24h; repeat mint for up to 25 tokens, and each comes back once, in the order asked. An observed item has at most 32 points, oldest first, each a time and an exact priceUsd. They are the prices Fin itself sampled from the data source while the token was in the feeds it reads, so an answer costs no provider read, and it is kept for 30 seconds. Use Get a token chart for one token's full chart.

An unavailable item says why it has no line: not_sampled when Fin read no price for it in the window, and too_sparse when what it read would mislead, because there are fewer than 8 prices, the first comes later than 15% into the window, or any gap, up to now, is over 25% of it. Leave the line out then rather than draw what there is. It needs the solana feature; a window Fin draws no line for, a mint that is no address, more than 25 mints or none answers 400.

Show where a token stands on its launchpad

List token launch status says where each token named stands, in one read for a page of a list:

HTTP
GET /v1/solana/tokens/launch-status?mint={mint}&mint={mint}

The SDK equivalent is user.solana.listTokenLaunchStatus({ mint: [first, second] }). Repeat mint for up to 25 tokens; each item has the token's mint and a status:

statusWithWhat it means
curvelaunchpad, progressPct, observedAtIt is on pump.fun's bonding curve, read from the chain. progressPct is how much of what the curve sells has been bought, cut to two decimals: 5.50.
graduatedlaunchpad, graduatedAtIt left its launchpad's curve for an open pool, at the time the data source states.
unknownFin cannot say: no launchpad is named for it, its launchpad's curve is not one Fin reads, or the chain or the data source could not be read just now.

Only pump.fun's curve can be read, so a token on another launchpad's curve is unknown; the launchpad and graduated of a token read still say where it launched. A read of the chain is kept for 15 seconds, and nothing is stored. It needs the solana feature; a mint that is no address, more than 25 mints or none answers 400. For one token, Get a Solana token states the same progress as bondingProgressPct, absent when it is on no curve Fin can read.

Draw a token's icon

A token's iconUrl, on a search candidate, a list row, a token read or a holding, is the path of Get a token icon for its mint:

HTTP
GET /v1/solana/tokens/{mint}/icon

The SDK equivalent is user.solana.getTokenIcon(mint), which answers { contentType, bytes }. Fin fetches the icon the data source lists itself, so the person's browser never asks the token creator's server for it, and answers it only as a PNG, JPEG, WebP or GIF, with Content-Type read from the image's own bytes, X-Content-Type-Options: nosniff and Cache-Control: private, max-age=86400: a day in the caller's own cache, never a shared one. Like every route it needs the user's session and your partner key, so an image tag reaches it through your own server. It answers 404 when there is no icon Fin will serve: none listed, or one that is unreachable, larger than 2 MiB (2,097,152 bytes), not one of those four types, or on an address that is not public. Draw a placeholder then.

If a public IPFS gateway listed for an icon answers 429, Fin can read that same content identifier and file path through its existing artwork gateway. Both attempts share the same three-second deadline, one-redirect limit and image checks; the browser still reads only Fin's icon route.

Trade a token from your own screen

A user can buy or sell a token from its page with one signature and no agent run. The trade runs through the same checks, policy worker and Solana sequence as a buy or sale the agent proposes and the user approves in chat; only who asked differs. It takes two calls and a read.

  1. Prepare a Solana trade with the buy or sale, in the shape the agent's solana_buy and solana_sell take: the token's mint, decimals and tokenProgram exactly as Get a Solana token read them, what it pays or sells, and an explicit maxValueLossBps from 1 to 1,500. Fin checks it as it checks the agent's own and answers the exact trade to show, authorization.message for the user to sign and the requestKey. Nothing is reserved, opened or moved.

``http POST /v1/users/{userId}/solana/trades/prepare ``

  1. Show the trade, have the user sign authorization.message with the wallet or passkey they signed in with, and place the trade before authorization.expiresAt, with the prepared requestKey as the Idempotency-Key:

```http POST /v1/users/{userId}/solana/trades Idempotency-Key: {requestKey}

{ "trade": { ...the prepared trade, unchanged }, "authorization": { ...the signed authorization } } ```

It answers 201 with the SolanaTrade, its status processing, and a Location header naming it. If the call times out, send it again unchanged: you get the same trade, never a second one. A different body under the same key is 409 request_key_conflict.

  1. Get the trade until its status is no longer processing. stage names the step it is on (funding, swap or sweep) once one began. Its status reads as a Solana activity item's does, paid, received and transactions included, and it is final by completeBy.

The SDK equivalents are user.solana.prepareTrade(body), user.solana.placeTrade(body, { idempotencyKey: prepared.requestKey }) and user.solana.getTrade(tradeId).

The signed message names completeBy: a trade that starts while the signature lasts may finish up to nine minutes after it, because a USDC buy first moves USDC to the agent's Solana account as SOL through 1Click and only then swaps on Jupiter, and a sale for USDC swaps, then sends its proceeds back. Nothing starts after the signature lapsed, and nothing runs past completeBy.

A buy needs the solana feature (403 solana_disabled) and opens the agent's Solana account itself the first time; it moves nothing to do so. A sale needs no feature, so a user can always sell what they hold, but it needs the opened account (404 no_account). A token Fin does not trade is 403 solana_token_not_tradable, read Fin's risk verdict before offering a buy. One trade runs at a time per user: placing a second while one runs is 409 solana_trade_changed, as is a token whose decimals or program changed under the signed trade; prepare it again. While an operator pauses trading, placing answers 503 unavailable, retryable, and a trade already running stops with nothing more moved.

Trades placed this way are in List activity as solana_trade items, each carrying the trade Get a Solana trade returns, apart from the agent's own solana items (and its solana_sell_many items, a sale of several coins under one approval) and left out under origin. When one ends, Fin notifies the user with a trade notification whose subject is { "type": "solana_trade", "tradeId": "…" }, so a user who left the page hears how it ended (see notifications). The agent's Solana balances change with them, so read Get the Solana account again once one ends.

Show where the data comes from

Answers carry their source and when it was read (source.name, source.observedAt; a chart's source is its price provider's). Show it beside the figures, such as "Data: Jupiter". Prices, liquidity and activity are the data source's own figures, converted without rounding, and not a quote: the price a trade gets is what its approval card and receipt state. Token and list answers are cached for up to thirty seconds, and charts for a minute, so a read repeated at once returns the same figures and the original observation time. Catalog discovery refreshes independently of a user's page. Provider update time, collection time and the user's most recent request are different facts; do not reset the market's apparent age when displaying cached data.

Financial endings and late confirmation

Solana approvals preserve exact price thresholds and the complete signed standing definition, even in a compact card. A standing firing renders the financial result without requiring a second approval for that call. pending, partial, not_executed and refused outcomes must not be displayed as successful settlement. A recorded refusal is a failed tool result with a denial code and repair advice; a later user request needs fresh approval.

A multi-coin sale (solana_sell_many, two to six coins under one approval, each sold on its own and then one transfer back) reports every coin in its outcome's solana.sales (sold with what it paid and the SOL its swap added, not_sold, or uncertain while a swap of it may still land, each with its own swap transactions) beside received, the whole sale's total; its solana.transactions lists only the transfer back, and it names no one token or paid. It is not_executed when no coin sold, partial when a coin sold but the transfer back did not finish (or the user kept SOL, solLeftLamports the summed gain), and settled once the one transfer settled. Its progress names the coin each swap sells (sale) and no transactionIndex.

solana.reconciled can correct a completed tool's still-pending financial result. Refresh the Solana account and balances when its financial status or reconciliation payload changes, even when the outer tool status remains completed. A missing transaction status alone never proves non-execution: retained history must cover the immutable pre-sign slot, otherwise Fin keeps the operation uncertain. USDC withdrawals recheck the approved loss floor against fresh SOL prices at signing, preserving the stricter of the original and fresh floors.

Fin documentation Built from the API contract · v1

Search all documentation