Token Forensics

Token-intelligence endpoints for holder discovery, metadata + mint security, wallet transaction history, first-funder analysis, and a combined token scan — the building blocks for wash-trading, bundle, sniper, and coordinated-entry detection.

Paid only — Starter tier and above. Free and anonymous callers receive 403. Authenticate with the x-api-key header (or ?apiKey= where convenient).

Access

• Anonymous / Free: not available (403 requires the starter tier or higher)
• Starter, Growth, Pro: available, increasing rate limits
• Rate-limit bucket: forensics (Starter 60/min, Growth 150/min, Pro 300/min)

All responses carry "source": "venum". Results are cached server-side per the TTLs noted on each endpoint; a cache hit adds "cached": true.

---

GET /v1/forensics/token/:mint/asset

Token metadata plus on-chain mint security (mint/freeze authority + revocation status, authoritative supply).

Path parameters:

• :mint — base58 mint address

curl https://api.venum.dev/v1/forensics/token/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/asset \
  -H 'x-api-key: YOUR_API_KEY'

Response (cached ~5 min):

{
  "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "asset": {
    "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
    "type": "fungible",
    "name": "Bonk",
    "symbol": "Bonk",
    "description": "The Official Bonk Inu token",
    "decimals": 5,
    "image": "https://arweave.net/hQiPZOsRZXGXBJd",
    "metadataUri": "https://arweave.net/QPC6FYdUn-3V8ytFNuoCS85S2tHAuiDblh6u3CIZLsw",
    "updateAuthority": "9AhKqLR67hwapvG8SA2JFXaCshXc9nALJjpKaHZrsbkw",
    "mutable": true,
    "burnt": false,
    "frozen": false,
    "compressed": false,
    "creators": [],
    "supply": "8799471827427647378",
    "security": {
      "mintAuthority": null,
      "freezeAuthority": null,
      "mintAuthorityRevoked": true,
      "freezeAuthorityRevoked": true
    }
  },
  "source": "venum"
}

• supply is the authoritative raw on-chain supply (string, to preserve precision beyond JS safe-integer range).
• security.mintAuthorityRevoked / freezeAuthorityRevoked are the key rug-risk signals (true = the authority is renounced).
• type is one of fungible, fungible-asset, nft, nft-print, programmable-nft, core-asset, core-collection, or unknown.

---

GET /v1/forensics/token/:mint/holders

Full, paginated holder list for a mint.

Path parameters:

• :mint — base58 mint address

Query parameters:

• limit — holders per page. Default 100, max 1000.
• page — 1-based page number. Default 1.
• cursor — opaque cursor for cursor-based pagination (alternative to page). When set, the response echoes the next cursor.

curl 'https://api.venum.dev/v1/forensics/token/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/holders?limit=1000&page=1' \
  -H 'x-api-key: YOUR_API_KEY'

Response (cached ~10s):

{
  "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "limit": 1000,
  "page": 1,
  "count": 1000,
  "cursor": null,
  "holders": [
    {
      "tokenAccount": "1163pYemGo7LTDRQRdVhNuWgrNFECKycf23Gi2vjCqB",
      "owner": "4VsCuKBVf5pdhT8Th6FPsf9gv7KiPX3EzAMggh5oye87",
      "amount": "5000000",
      "delegatedAmount": "0",
      "frozen": false
    }
  ],
  "source": "venum"
}

Token amounts are raw (string). Paginate by incrementing page (or following cursor) until count < limit.

---

GET /v1/forensics/address/:address/transactions

Transaction history for any address (wallet or mint).

Path parameters:

• :address — base58 address

Query parameters:

• limit — signatures per page. Default 100, max 1000.
• before — return signatures older than this signature (page back).
• until — stop at this signature.
• order — desc (default, newest-first) or asc (oldest-first within the page).
• parsed — true to enrich each row with decoded detail (fee payer, instruction list, SOL + token balance deltas). Enrichment is applied to the first parseCap rows (default 100); for deeper parsed windows, paginate.

curl 'https://api.venum.dev/v1/forensics/address/YOUR_WALLET_ADDRESS/transactions?limit=100&parsed=true' \
  -H 'x-api-key: YOUR_API_KEY'

Response (cached ~10s):

{
  "address": "YOUR_WALLET_ADDRESS",
  "order": "desc",
  "count": 100,
  "parseCap": 100,
  "nextBefore": "562oPNioBM8rPLcAbaXqrRgUkKW8PyeTucchHwakFjCB...",
  "transactions": [
    {
      "signature": "562oPNioBM8rPLcAbaXqrRgUkKW8PyeTucchHwakFjCB...",
      "slot": 428183497,
      "blockTime": 1782141307,
      "error": false,
      "confirmationStatus": "finalized",
      "memo": null,
      "detail": {
        "feePayer": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
        "feeLamports": 5000,
        "solPreLamports": 0,
        "solPostLamports": 9960527550,
        "solChangeLamports": 9960527550,
        "programs": ["11111111111111111111111111111111"],
        "instructions": [
          { "program": "system", "programId": "11111111111111111111111111111111", "type": "transfer" }
        ],
        "tokenChanges": [
          { "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "preAmount": "0", "postAmount": "1000000", "change": "1000000" }
        ]
      }
    }
  ],
  "source": "venum"
}

• detail is present only when parsed=true, and only on the first parseCap rows.
• error is true when the transaction failed on-chain.
• Use nextBefore as the before parameter to page toward older history.
• order=asc reverses the current page; to reach the genuinely earliest transactions, page with before to the end (see first-funder, which does this walk for you).

---

GET /v1/forensics/address/:address/first-funder

The first inbound funder of an address — walks back to its earliest transaction and reports who sent the first SOL.

Path parameters:

• :address — base58 address

curl https://api.venum.dev/v1/forensics/address/YOUR_WALLET_ADDRESS/first-funder \
  -H 'x-api-key: YOUR_API_KEY'

Response (cached; immutable once the true earliest is reached):

{
  "address": "YOUR_WALLET_ADDRESS",
  "firstFunder": "En3NPq8o9Cyn...",
  "method": "transfer",
  "amountSol": 0.00001,
  "signature": "2x3dkAJ3nsH4...",
  "slot": 423865007,
  "blockTime": 1782141606,
  "walkedPages": 1,
  "truncated": false,
  "source": "venum"
}

• method — how the funder was determined: transfer, create-account, or balance-delta (fallback). null when no inbound funding was found in the earliest transaction (firstFunder is then null).
• truncated — true if the address is too active to reach its genesis transaction within the walk cap; the result is then the earliest within the cap and is not cached as immutable.

---

GET /v1/forensics/token/:mint/scan

Combined scan: top holders by balance, each resolved to its owner wallet and (optionally) its first funder — in a single call.

Rolling out. Top-holder ranking relies on an account-index backend that is being provisioned. Until it lands this endpoint may return 502; the underlying primitives (/holders, /first-funder) are unaffected.

Path parameters:

• :mint — base58 mint address

Query parameters:

• holders — number of top holders to analyze. Default 20, max 20.
• funders — false to skip the first-funder lookup (top holders only). Default true.

curl 'https://api.venum.dev/v1/forensics/token/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/scan?holders=20' \
  -H 'x-api-key: YOUR_API_KEY'

Response (cached ~30s):

{
  "mint": "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
  "holderCount": 20,
  "topHolders": [
    {
      "tokenAccount": "5hpfC9VBxVcoW9opCnM2PqR6YWRLBzrBpabJTZnwwNiw",
      "owner": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
      "amount": "699666605122337574",
      "decimals": 5,
      "uiAmount": 6996666051223.375,
      "firstFunder": "En3NPq8o9Cyn...",
      "firstFunderSignature": "2x3dkAJ3nsH4...",
      "firstFunderAmountSol": 0.00001
    }
  ],
  "source": "venum"
}

With funders=false, the firstFunder* fields are omitted. topHolders is ordered by balance, descending.

---

Notes

• All amounts are raw token units (strings) unless suffixed Sol/Lamports.
• Holder and history data reflect recent on-chain state; metadata, supply, and first-funder are cached more aggressively (first-funder is immutable once the earliest transaction is reached).
• Errors are returned as { "error": "<message>" } with 400 (bad address), 404 (not found), 502 (upstream failure), or 503 (temporarily unavailable).