Overview
The SP Passport API is a read-only REST endpoint that returns verified holder identity data for any Solana wallet address registered in the Smart Pocket ecosystem.
It enables external dApps, DeFi protocols, and communities to implement token-gated access, loyalty rewards, and reputation systems based on SP holding behavior — without requiring users to re-verify on each platform.
Authentication
All requests must include a valid API key in the X-API-Key header. Keys are issued per wallet address and can be managed in the API Keys section below.
Request Header
| Header | Required | Description |
|---|---|---|
| X-API-Key | Required | Your API key (format: sp_live_...) |
API Keys
Enter your Solana wallet address to manage your API keys. Keys are tied to your wallet and can be revoked at any time. Maximum 5 active keys per wallet.
Endpoint
https://sptoken.io/api/passport/:wallet:wallet with a valid Solana wallet address (base58, 32–44 characters).Path Parameter
| Parameter | Type | Description |
|---|---|---|
| wallet | string | Solana wallet address (base58 encoded) |
Response Schema
Success Response (200)
{
"success": true,
"passport": {
"wallet": "6gdDALVM7FrTnXTXo17PpHnLtUdnaAtokCBzPUZKA2rx",
"holderRank": "Gold",
"spBalance": 15000,
"holdDays": 120,
"totalPoints": 1800,
"referralCount": 5,
"referralPoints": 250,
"pohScore": 496,
"verifiedAt": "2026-03-27T00:00:00.000Z"
}
}Response Fields
| Field | Type | Description |
|---|---|---|
| wallet | string | Solana wallet address |
| holderRank | string | Holder tier: Newcomer / Bronze / Silver / Gold / Diamond / Whale |
| spBalance | number | Total SP points (proxy for on-chain balance) |
| holdDays | number | Number of days holding SP tokens |
| totalPoints | number | Cumulative earn points accumulated |
| referralCount | number | Number of unique wallets referred |
| referralPoints | number | Points earned through referrals |
| pohScore | number | Proof-of-Hold score (0–1000), composite loyalty metric |
| verifiedAt | string | ISO 8601 timestamp of verification |
Error Responses
// 401 Unauthorized — missing or invalid API key
{ "error": "Missing API key. Add X-API-Key header. Get your key at /docs/passport", "docs": "/docs/passport" }
// 400 Bad Request
{ "error": "Invalid wallet address" }
// 404 Not Found
{ "error": "Wallet not registered in Smart Pocket" }
// 500 Internal Server Error
{ "error": "Internal server error" }Holder Ranks
Code Examples
curl -X GET \
"https://sptoken.io/api/passport/YOUR_WALLET_ADDRESS" \
-H "X-API-Key: sp_live_YOUR_API_KEY" \
-H "Accept: application/json"Token Gating Example
// Example: Gate content by holder rank
const res = await fetch(`https://sptoken.io/api/passport/${userWallet}`, {
headers: { "X-API-Key": "sp_live_YOUR_API_KEY" },
});
const { passport } = await res.json();
const ALLOWED_RANKS = ["Silver", "Gold", "Diamond", "Whale"];
if (ALLOWED_RANKS.includes(passport.holderRank)) {
// Grant access to premium content
showPremiumContent();
} else {
// Redirect to purchase page
redirectToBuyPage();
}Use Cases
Restrict premium content, Discord channels, or dApp features to Silver+ holders.
Reward users based on pohScore — higher scores unlock better rates or bonuses.
Use SP Passport as a portable identity layer across multiple DeFi protocols.
Weight voting power by holderRank or pohScore for fairer governance.
Rate Limits & Caching
Responses include Cache-Control: public, max-age=60. Data refreshes every 60 seconds.
All origins are allowed (Access-Control-Allow-Origin: *). No preflight required for GET requests.
Please cache responses on your end and avoid polling more than once per minute per wallet. Abusive traffic may result in API key suspension. For high-volume integrations, contact us via Telegram.
Get your API key above and start building with the SP Passport API today.