Skip to main content

​
Solana API

Query Solana wallet balances and token holdings, verify Agentbot token holder benefits for baseFM, fetch live SOL market data, and save per-user RPC endpoint configurations.

​
Get SOL price

GET /api/solana/price
Returns the current SOL price in USD along with 24-hour market data. Data is sourced from CoinGecko and cached for 60 seconds.

​
Response

{
  "price": 148.52,
  "change24h": -2.34,
  "marketCap": 72500000000,
  "volume24h": 3200000000
}

​
Response fields

FieldTypeDescription
pricenumber | nullCurrent SOL price in USD
change24hnumber | null24-hour price change percentage
marketCapnumber | nullMarket capitalization in USD
volume24hnumber | null24-hour trading volume in USD
Fields return null when CoinGecko does not include them in the response. Price data is cached and refreshed every 60 seconds.

​
Errors

CodeDescription
500Failed to fetch price data from CoinGecko

​
Look up wallet

GET /api/solana/wallet
Returns the SOL balance, token holdings, and account metadata for a Solana address. Requires session authentication. The endpoint uses the user’s saved RPC configuration (see save RPC configuration) or falls back to the platform default.

​
Query parameters

ParameterTypeRequiredDescription
addressstringYesSolana wallet address (base58-encoded, 32–44 characters). Invalid addresses return a 400 error.
rpcstringNoDeprecated. This parameter is no longer accepted. The endpoint now uses your saved RPC configuration or the platform default. Any value passed for rpc is ignored.

​
Response

{
  "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "solBalance": 1.5,
  "tokens": [
    {
      "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "symbol": "USDC",
      "amount": 250.0,
      "decimals": 6
    },
    {
      "mint": "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
      "symbol": "JUP",
      "amount": 100.0,
      "decimals": 6
    }
  ],
  "accountInfo": {
    "isExecutable": false,
    "owner": "11111111111111111111111111111111",
    "rentEpoch": 18446744073709551615
  }
}

​
Response fields

FieldTypeDescription
addressstringThe queried wallet address
solBalancenumberNative SOL balance (in SOL, not lamports)
tokensarraySPL token holdings with a non-zero balance, sorted by amount descending (max 20)
tokens[].mintstringToken mint address
tokens[].symbolstringToken symbol. Known tokens display their ticker (e.g. USDC, JUP); unknown tokens show a truncated mint address.
tokens[].amountnumberToken balance in human-readable units
tokens[].decimalsnumberToken decimal precision
accountInfoobjectOn-chain account metadata
accountInfo.isExecutablebooleanWhether the account contains an executable program
accountInfo.ownerstring | nullProgram that owns this account
accountInfo.rentEpochnumber | nullEpoch at which rent was last collected

​
Recognized tokens

The following token mints are resolved to human-readable symbols automatically:
SymbolMint addressDecimals
USDCEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v6
USDTEs9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB6
WSOLSo111111111111111111111111111111111111111129
JUPJUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN6
BONKDezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB2635
WIFEKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm6
mSOLmSoLzYCxHdYgdzU16g5QSh3i5K3z3KZK7ytfqcJm7So9
stSOL7dHbWXmci3dT8UFYWYZweBLXgycu7Y3iL6trKn1Y7ARj9
Tokens not in this list display a truncated mint address as the symbol.

​
Errors

CodeDescription
400Invalid Solana address. The address must be a base58-encoded string between 32 and 44 characters.
401Unauthorized — no valid session. This endpoint now requires authentication.
500Failed to fetch wallet data from the Solana RPC endpoint

​
Verify holder benefits

GET /api/solana/verify
Checks the Agentbot token balance for a Solana wallet address and returns the holder’s baseFM benefit tier. No authentication required.

​
Query parameters

ParameterTypeRequiredDescription
addressstringYesSolana wallet address (base58-encoded, 32–44 characters). Invalid addresses return a 400 error.

​
Response

{
  "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "token": "9V4m199eohMgy7bB7MbXhDacUur6NzpgZVrhfux5pump",
  "balance": 15000,
  "eligible": true,
  "benefits": [
    { "tier": "Holder", "perk": "Access to exclusive baseFM DJ streams" },
    { "tier": "Builder", "perk": "Early access to new features + premium playlists" }
  ],
  "tiers": [
    { "name": "Holder", "min": 1000, "credits": 50, "basefm": "Exclusive DJ streams" },
    { "name": "Builder", "min": 10000, "credits": 100, "basefm": "Early features + premium playlists" },
    { "name": "Whale", "min": 100000, "credits": 200, "basefm": "VIP chat + voting + revenue share" }
  ]
}

​
Response fields

FieldTypeDescription
addressstringThe queried wallet address
tokenstringAgentbot token mint address on Solana
balancenumberToken balance in human-readable units
eligiblebooleantrue when balance is at least 1,000 tokens (Holder tier minimum)
benefitsarrayList of benefit tiers the wallet qualifies for based on its current balance
benefits[].tierstringTier name (Holder, Builder, or Whale)
benefits[].perkstringDescription of the perk granted by this tier
tiersarrayAll available benefit tiers regardless of the wallet’s balance
tiers[].namestringTier name
tiers[].minnumberMinimum token balance required for this tier
tiers[].creditsnumberNumber of platform credits granted at this tier
tiers[].basefmstringbaseFM perk description for this tier

​
Benefit tiers

TierMinimum balanceCreditsbaseFM perk
Holder1,00050Access to exclusive baseFM DJ streams
Builder10,000100Early access to new features + premium playlists
Whale100,000200VIP community chat + voting rights + revenue share
A wallet qualifies for all tiers at or below its balance. For example, a wallet with 15,000 tokens qualifies for both Holder and Builder benefits. The benefits array only includes tiers the wallet meets; the tiers array always returns all three tiers.

​
Errors

CodeDescription
400Invalid Solana address. The address must be a base58-encoded string between 32 and 44 characters.
502Failed to communicate with the Solana RPC endpoint

​
Get RPC configuration

GET /api/solana/rpc-config
Returns the Solana RPC URL for the authenticated user, along with the default fallback URL and the configuration source. Requires session authentication.

​
Response

{
  "rpcUrl": "https://my-custom-rpc.example.com",
  "defaultRpcUrl": "https://api.mainnet-beta.solana.com",
  "source": "user"
}

​
Response fields

FieldTypeDescription
rpcUrlstringThe active RPC URL. Returns the user’s saved custom URL if one exists, otherwise returns the platform default RPC URL.
defaultRpcUrlstringThe platform default Solana RPC URL used as a fallback when no custom URL is configured.
sourcestringIndicates where the rpcUrl value comes from. Either "user" (a saved custom URL) or "default" (the platform fallback).

​
Errors

CodeDescription
401Unauthorized — no valid session

​
Save RPC configuration

POST /api/solana/rpc-config
Saves or updates the custom Solana RPC URL for the authenticated user. Only HTTPS URLs are accepted. Requires session authentication.

​
Request body

FieldTypeRequiredDescription
rpcUrlstringYesA valid HTTPS URL for the custom Solana RPC endpoint

​
Example request

{
  "rpcUrl": "https://my-custom-rpc.example.com"
}

​
Response

{
  "success": true,
  "rpcUrl": "https://my-custom-rpc.example.com"
}

​
Errors

CodeDescription
400Missing rpcUrl, value is not a string, URL is invalid, or URL does not use HTTPS
400RPC URL contains a placeholder value (e.g. a template URL that ends with an empty api-key= parameter or includes an example hostname). You must provide a complete provider URL.
401Unauthorized — no valid session