Feyn API

Getting started

Quickstart

1. Get a key. Buy a credit pack on the pricing page with one payment from your Solana wallet. The starter pack is $25 for 6,000 credits. The key is shown once; keep it in an environment variable.
2. Ask for a token. One report costs 1 credit. Every response says how many are left in X-Feyn-Credits-Remaining.
3. Read the verdict. token.verdict.level is scam (an S-class finding fired), high_risk or caution (M-class findings only; the site shows these as “Warning · high risk” and “Warning”, since an M class firing does not make a token malicious), clean (nothing fired: no flags, which is not a promise) or insufficient_data.

curl https://api.feyn.fun/v1/token/B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump \
  -H "Authorization: Bearer $FEYN_API_KEY"

const res = await fetch("https://api.feyn.fun/v1/token/B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump", {
  headers: { Authorization: `Bearer ${process.env.FEYN_API_KEY}` },
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.msg}`);
}
const report = await res.json();
console.log(report.token.verdict.level, report.token.verdict.headline);
console.log("credits left:", res.headers.get("X-Feyn-Credits-Remaining"));

import os
import requests

res = requests.get(
    "https://api.feyn.fun/v1/token/B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump",
    headers={"Authorization": f"Bearer {os.environ['FEYN_API_KEY']}"},
    timeout=10,
)
res.raise_for_status()
report = res.json()
print(report["token"]["verdict"]["level"], report["token"]["verdict"]["headline"])
print("credits left:", res.headers["X-Feyn-Credits-Remaining"])

Until the $FEYN launch, leave the key out: the same request is free, within the per-IP rate limits. From the launch it answers 402 without one.

Authentication

Send your API key as a bearer token. Keys start with feyn_sk_. Feyn stores only a hash of each key, so keep yours out of client-side code and logs.

GET /v1/token/B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump HTTP/1.1
Host: api.feyn.fun
Authorization: Bearer feyn_sk_…

Every keyed response carries two headers:

What is free: a bad address (400) or an unknown token (404) is answered before any charge. A 304 revalidation is refunded. If the server fails after charging (5xx), the credits come back.

The website, the Telegram bot, the WebSocket, /v1/resolve, /v1/blob and /healthz need no key.

Paying with x402

Available at launch Payments open at the $FEYN launch.

Payments use x402 v2 with the Solana exact scheme: a 402 answer carries a quote, you pay it with one token transfer, and repeat the request with the payment attached. Feyn runs its own facilitator and pays the network fee. Pay in USDC at list price, or in $FEYN at 15% off. SOL is not accepted.

Single call

Without a key, GET /v1/token/{mint} costs $0.01 per report, paid on the request itself. Paid attempts are limited to 2 per second per IP.

The transaction must have exactly this shape, or it is refused before broadcast:

Two signers only (the fee payer extra.feePayer at index 0, then you), no address lookup tables, no extra instructions. Wallets that inject Lighthouse assertions are refused.

{
  "x402Version": 2,
  "error": "payment required",
  "resource": {
    "url": "https://api.feyn.fun/v1/token/B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump",
    "description": "Feyn token report",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "10000",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "payTo": "<vault owner>",
      "maxTimeoutSeconds": 300,
      "extra": {
        "feePayer": "<facilitator>",
        "memo": "feyn1:c:usdc:10000:<exp>:<nonce>:<mac>",
        "name": "USDC",
        "decimals": 6
      }
    },
    {
      "…": "the same for $FEYN at 15% off (maxTimeoutSeconds ≤ 60), while a TWAP quote exists"
    }
  ]
}

# 1. The quote
curl -si https://api.feyn.fun/v1/token/B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump | grep -i payment-required

# 2. Sign the transfer with an x402 v2 client, then:
curl https://api.feyn.fun/v1/token/B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump \
  -H "PAYMENT-SIGNATURE: $PAYMENT_B64"

const url = "https://api.feyn.fun/v1/token/B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump";

// 1. The quote: a 402 whose PAYMENT-REQUIRED header lists one option per asset.
const quote = await fetch(url);
const required = JSON.parse(atob(quote.headers.get("PAYMENT-REQUIRED")));
const usdc = required.accepts[0];

// 2. Build and sign the transfer (any x402 v2 client for Solana "exact" does this).
const payload = await x402Client.createPayment(usdc);

// 3. The same request, paid.
const res = await fetch(url, {
  headers: { "PAYMENT-SIGNATURE": btoa(JSON.stringify(payload)) },
});
const report = await res.json();

import base64
import json
import requests

url = "https://api.feyn.fun/v1/token/B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump"

# 1. The quote
quote = requests.get(url, timeout=10)
required = json.loads(base64.b64decode(quote.headers["PAYMENT-REQUIRED"]))
usdc = required["accepts"][0]

# 2. Build and sign the transfer with an x402 v2 client
payload = x402_client.create_payment(usdc)

# 3. The same request, paid
res = requests.get(url, headers={"PAYMENT-SIGNATURE": base64.b64encode(json.dumps(payload).encode()).decode()}, timeout=60)
report = res.json()

Credit packs

A pack is bought the same way, from POST /v1/keys?pack=…: the paid request answers 201 with the key. A payment buys exactly one key; a replayed payment is refused. The key becomes active once its payment is final (usually within seconds; otherwise the answer is 202 and the key activates on first use).

USDC quotes hold for 300 seconds and $FEYN quotes for 60. The $FEYN price is a 10-minute average of its own trades; no $FEYN quote is offered while that price is unreliable, and USDC is always offered. On the website, the pricing page does all of this with your wallet.

Plans and pricing

Every call with a pack's key spends credits; Enterprise calls spend none. Prices and costs below come from the same configuration the API server loads. $FEYN prices are 15% below the USDC price.

A key's lifetime counts from its payment. Credits left at expiry expire with it. Every plan gets the same reports; Enterprise adds the firehose, 24/7 support and monthly renewal of the same key.

Rate limits

Each key has its own limit, set by its pack. Over it, the answer is 429 rate_limited with Retry-After (seconds) and retry_after_s in the body.

Payments have two more limits that protect the fee payer. A network (IPv4 /24, IPv6 /48) whose payments failed on chain and used its share of the fee budget gets 429 network_throttled for 5 minutes. Under a drain attempt new payers settle one at a time, and a payment that waits over 10 s gets 503 settlement_busy. API keys are never affected by either.

Errors

Every error has the same JSON body. Switch on code, never on msg. retry_after_s (and the Retry-After header) appear when waiting helps.

{
  "error": {
    "code": "key_expired",
    "msg": "key expired",
    "request_id": "01J9…",
    "retry_after_s": 5
  }
}

A refused payment answers 402 with fresh quotes and a PAYMENT-RESPONSE whose errorReason says why:

invalid_payment_requirements

The quote is unknown, altered or expired. Ask for a fresh 402 and pay again.

duplicate_settlement

This payment was already used. One payment buys exactly one key or call.

insufficient_funds

The paying wallet does not hold enough of the asset.

invalid_transaction_state

The payment transaction failed on chain.

invalid_exact_svm_payload_transaction_*

The transaction is not exactly the accepted shape (compute budget, one TransferChecked, the memo).

The insiders object

token.insiders, in the report and the summary: every wallet a shown scam or malicious finding names (the creator, launch-block buyers, linked clusters and hubs, snipers, wash traders and bots), each counted once, and what that set did with the token. Shares are basis points oftoken.supply_raw. The object is absent when no finding names a wallet. It updates live, with every trade of the token.

• Tokens moving between insiders cancel out. What reached the set from outside by transfer counts as received; what left it without a sale (sent to another wallet, or burned) counts as sent, not as sold.
• Transfers are followed: a wallet that received the token from an insider outside a trade (and, a few hops on, its own recipients) counts as an insider of the sender's group. What it holds is in held_bps, what it sells in sold_bps and the profit, and the transfer is not sent. followed_wallets says how many such wallets are counted. Exchanges, routers, programs and dust recipients are never followed: tokens sent there stay sent.
• Wash traders (M001 to M003 wash wallets, M010 bots) are counted net: tokens they bought and sold back add to neither bought nor sold. Their SOL stays gross in buy_quote and sell_quote, since a round trip costs real fees.
• Flagged traders (M011) are not insiders: their record is on other tokens.

The outcomes object

token.outcomes, in the report and the summary: what happened to earlier launches that looked like this token at the same age. Historical, not a prediction and not advice. It is computed from a versioned table (table) of Feyn's own history, for pump.fun launches Feyn saw from creation, on their curve and not in Mayhem mode; other tokens have no outcomes.

• at_secs is the comparison point (120, 300, 900 or 3600 seconds after launch): the latest one the token had reached. Its signals and trading activity are compared with other launches' at that age. After 90 minutes the last object stays as it was.
• activity: 0 = no trade in the preceding minute; 1–5 = quintile of the SOL bought so far among launches still trading (5 = most). Every rate is within this bucket.
• rows: one per qualifying signal the token has (signal: a class id such as S006, or M021_copy, launch_block_30, top10_25, creator_5, creator_serial, creator_sold), with label, and the rates of comparable launches with and without it. similar is every comparable launch.
• Rates are in basis points of the group: crashed_80_1h_bps (price fell to 20% or less within the next hour), doubled_6h_bps (reached 2× within 6 hours), graduated_24h_bps (curve completed within 24 hours of launch). n / n_24h are the group sizes; a rate is absent when its group is under min_n.

The clusters object

token.clusters, in the report and the summary: wallets on this token (its insiders and its creator) that belong to a wallet cluster, a group of wallets that trade as one across many launches. Absent when none does. At most 3 clusters, highest confidence first.

• Clusters are found from trading behaviour over the last few days of pump.fun launches: the same launches bought within a few blocks of each other, correlated activity, identical buy sizes. Not from funding or signer links: a cluster says the wallets act as one group (one operator or a coordinated group), not who controls them. Recomputed every hour; only clusters with confidence of 60 or more and same-block evidence are listed.
• confidence (0–100) is calibrated: of clusters rated 70, about 70% were confirmed by an independent on-chain link check.
• members[]: the cluster's wallets on this token (at most 12; members_more counts the rest), each a (an index into addrs; the summary's own addrs covers only the creator, curve and pool, so resolve it in the report's or the addrs section's table) and its insider role (as in insiders.groups; creator for the creator). creator is set when the creator is a member; insiders counts the token's insiders it covers; size is the whole cluster.
• Cluster-wide, over the computation's window (window_hours, generation): together (launches two of its wallets bought within a few blocks of each other), same_block_bps and identical_bps (of those co-buys, the share in the same block / with identical sizes), early_bps (first buys made right after launch), overlap_bps (overlap of the launches they bought), activity_corr_bps (correlation of their activity over time), onchain_link (an on-chain link also joins two of them), staggered_bps (optional: of the launches two of its wallets bought, the share bought one after another, more than a minute and at most ten minutes apart).

Messages

→ {"type":"hello","v":1,"codecs":["deflate-raw"]}
→ {"type":"sub","id":1,"q":"B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump"}
← {"type":"hello_ack","v":1,"server_time":1790416804123,"max_subs":4,"codecs":["deflate-raw"],"ping_interval_s":30}
← {"type":"resolved","id":1,"q":"B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump","kind":"mint","mint":"B4HpTokrHXwYGQUYCN1axBH54pYf483Bpw5sCft2pump","name":"Example Small Curve","symbol":"SMOL"}
← [01 01 01 00 00 00] summary summary · deflate-raw · 1022 B
← [00 02 01 00 00 00] section addrs · identity · 227 B
← [01 02 01 00 00 00] section malicious/M004 · deflate-raw · 541 B
← [00 02 01 00 00 00] section context · identity · 348 B
← [01 02 01 00 00 00] section tables/block0_buyers · deflate-raw · 422 B
← [01 02 01 00 00 00] section tables/holders · deflate-raw · 414 B
← {"type":"done","id":1,"rev":450641306003,"mode":"snapshot","hashes":{"addrs":"9bc01ae70874bc54","context":"ff7ccdae6732ed75","malicious/M004":"d9b2b17dca920c51","summary":"12ef3c252b3985d2","tables/block0_buyers":"15880e004c033b06","tables/holders":"0fab2cce775fb660"}}

Binary frames

Every binary frame starts with a 6-byte header, then the payload: JSON, deflated with raw DEFLATE when it is 512 bytes or more and you listed the codec.

Process frames in arrival order (decompression is asynchronous). Drop frames with an unknown codec or kind, and frames for subs you no longer hold.

Limits and errors

Per socket: 4 subs, 10 sub/s, 20 get/s, 50 messages/s, frames up to 2,048 bytes. Per IP: 60 new sockets a minute, 30 lookups a minute (burst 15; a token you looked up in the last 10 minutes is free), 32 live subs. After 20 refused lookups in 10 minutes an IP is challenged (Turnstile). Reconnect with backoff 0.25 → 0.5 → 1 → 2 → 4 → 8 s, then resume each sub with its rev.

Enterprise plan

Enterprise is $1,500 a month ($1,275 in $FEYN). It is bought like a pack, with POST /v1/keys?pack=enterprise or on the pricing page, and its key includes:

• The firehose (below): every finding as it happens, new, updated or retracted, across all pump.fun and PumpSwap tokens, on one WebSocket.
• Unlimited report lookups. Keyed calls spend no credits; X-Feyn-Credits-Remaining reads unlimited.
• 2,000 requests/s, bursts of 4,000.
• 24/7 support in a private Telegram channel. Message @reaperofrugs on Telegram to set up your private support channel, before you buy or once you have the key. /v1/pricing and /v1/keys/self carry the handle as support_telegram.

Renewal. The key lasts 30 days from its payment. Paying again with the same key (renewal, or Renew on the key page) adds 30 days to it. The key, its firehose cursor and your setup stay the same, and nothing renews by itself. From 3 days before expiry, /v1/keys/self has renewal.due: true and the firehose sends a key_expiring notice.

Firehose messages

Every message is one JSON text frame with a type. Events carry seq, cursor (store the last one you processed) and t (unix ms). They describe state, not edits: treat each as an upsert keyed by (mint, key), so applying one twice is harmless. Ignore unknown fields and types.

A finding names the token (mint, token), the finding (class, an S or M code, with name and headline), what happened to it (event) and the token's verdict after the change. For the evidence, fetch the report (GET /v1/token/{mint}, unlimited on this plan) or subscribe to the token on the WebSocket. A retracted finding no longer holds.

Resume and back-pressure

Resume. Reconnect, and send the last cursor you processed in hello.cursor. hello_ack.start says what happens:

live

No cursor: the stream starts from the next event.

replay

Your cursor is from this server process and still in its ring (65,536 events): exactly the events after it, in order.

approx

Your cursor is from the other app server or a previous process: replay by time from 2 s before it. Events may repeat; they are upserts.

resync

Your cursor is older than the ring or the process: a resync (cursor_expired) follows, then the live stream. Re-read the tokens you track.

Back-pressure. Every socket reads one shared, bounded ring at its own position, so a slow socket never delays the stream or anyone else. Fall more than max_lag (32,768) events behind, or leave a write blocked for 10 s, and you get resync (reason slow_consumer), then close 4008. Reconnect with your last processed cursor. Read in one task and process in another, so a slow handler does not stall the socket.

Reconnect after any other close with a short random delay, and resume with your last cursor.

More

Changelog

1. 28 Sep 2026

   API v1, first public version. Reports (feyn.report/1), the WebSocket (feyn.ws/1), API keys and x402 payments in USDC or in $FEYN at 15% off.

2. 29 Sep 2026

   New plan lineup and Enterprise. Packs from $25; Enterprise at $1,500 a month with the firehose (/v1/firehose), unlimited lookups and renewal of the same key. Additive: /v1/pricing, POST /v1/keys and /v1/keys/self (now also /v1/keys/me) gain fields.

3. 23 Oct 2026

   Wallet clusters. Reports and summaries gain token.clusters (the clusters object): the token's insiders and creator that belong to a group of wallets trading as one across many launches, with the group's confidence and figures. Additive.

4. 23 Oct 2026

   Insider transfers followed. A wallet that received the token from an insider outside a trade now counts as an insider: its holdings and sells are the insiders', instead of the tokens counting as sent. token.insiders gains followed_wallets, followed_held_bps and followed_sold_bps. Additive.

5. 5 Oct 2026

   Outcomes and launch facts. Reports and summaries gain token.outcomes (the outcomes object): historical outcome rates of comparable launches. The report's context gains the keys creator_launches (the creator's other launches in the 24 hours before), creator_sold and holder_concentration. Informational: neither changes the verdict. Additive.

6. 2 Oct 2026

   Insiders with unknown history. token.insiders gains unknown_wallets and figures_unavailable: an insider whose trades on the token Feyn no longer holds is left out of the figures (marked at_least), never counted as 0. Additive.

7. 2 Oct 2026

   Insiders, net of round trips. token.insiders gains net_bought_bps, net_sold_bps, round_trip_bps and held_of_net_bought_bps (and per group net_bought_bps, net_sold_bps, received_bps, sent_bps, so each group adds up on its own): a wallet's buys it sold back no longer count as supply bought. The gross bought_bps / sold_bps keep their meaning and cap at 100%; the site shows them while they stay under 100% and the net pair once they reach it. Additive.

8. 1 Oct 2026

   Insiders. Reports and summaries gain token.insiders (the insiders object): how much of the supply the wallets named by the findings bought, sold and still hold, and their realised profit. Additive.

9. Versioning

   The path carries the major version (/v1). New optional fields, message types, section keys and error codes are added without a new version, so ignore what you don't know. A breaking change moves to /v2.