REST API Endpoints

Complete reference for all GoonPad REST API endpoints.

Base URL

https://api.goonpad.dev/api

Token Endpoints

GET /tokens

Returns all tokens on the platform.

Query Parameters:

limit (number, optional) - Limit number of tokens returned

Response:

json

{
  "success": true,
  "data": [
    {
      "address": "7xKXtg2CW87d97...",
      "name": "Goon Coin",
      "symbol": "GOON",
      "decimals": 9,
      "supply": "1000000000",
      "price": 0.0000425,
      "marketCap": 42.5,
      "volume24h": 125.3,
      "holders": 847,
      "mint": "7xKXtg2CW87d97...",
      "poolAddress": "PoolStateAddress...",
      "creator": "9YzWk8vJVh3yG...",
      "createdAt": 1704067200,
      "graduated": false,
      "solRaised": 42.5,
      "totalSupply": 1000000000,
      "pricePerToken": 0.0000425,
      "graduationTarget": 85,
      "bondingCurveProgress": 0.5,
      "tokensRemaining": 500000000,
      "imageUrl": "https://...",
      "description": "The best meme coin",
      "livestreamUrl": "https://...",
      "isLive": false,
      "feesClaimed": false
    }
  ],
  "source": "cache"
}

Note: Most fields are optional and may not be present for all tokens.

Example:

bash

curl https://api.goonpad.dev/api/tokens

Returns tokens approaching graduation (70%+ bonding curve progress, not yet graduated).

Response: Same format as /tokens but filtered.

Example:

bash

curl https://api.goonpad.dev/api/tokens/trending

GET /tokens/nutted

Returns graduated tokens (reached 85 SOL and migrated to Raydium).

Response: Same format as /tokens but filtered for graduated tokens only.

Example:

bash

curl https://api.goonpad.dev/api/tokens/nutted

GET /tokens/:address

Returns detailed information for a specific token.

Parameters:

address (string, required) - Token mint address OR pool address

Response:

json

{
  "success": true,
  "data": {
    "address": "7xKXtg2CW87d97...",
    "name": "Goon Coin",
    "symbol": "GOON",
    "decimals": 9,
    "supply": "1000000000",
    "price": 0.0000425,
    "marketCap": 42.5,
    "volume24h": 125.3,
    "holders": 847,
    "mint": "7xKXtg2CW87d97...",
    "poolAddress": "PoolStateAddress...",
    "creator": "9YzWk8vJVh3yG...",
    "createdAt": 1704067200,
    "graduated": false,
    "solRaised": 42.5,
    "totalSupply": 1000000000,
    "pricePerToken": 0.0000425,
    "graduationTarget": 85,
    "bondingCurveProgress": 0.5,
    "tokensRemaining": 500000000,
    "imageUrl": "https://...",
    "description": "The best meme coin"
  },
  "source": "cache"
}

Example:

bash

curl https://api.goonpad.dev/api/tokens/7xKXtg2CW87d97...

GET /tokens/:address/nutjar

Returns Nut Jar (fee accumulation) status for a token.

Parameters:

address (string, required) - Token mint address

Response:

json

{
  "success": true,
  "data": {
    "totalAccumulated": 1.5,
    "creatorShare": 0.45,
    "platformShare": 1.05,
    "status": "accumulating",
    "timeUntilExpiry": 43200,
    "distributionType": null
  }
}

Status Values:

accumulating - Fees collecting, token active
ready - Token graduated, fees claimable
expired - Token didn't graduate in 24h

Example:

bash

curl https://api.goonpad.dev/api/tokens/7xKXtg2CW87d97.../nutjar

GET /tokens/:address/holders

Returns number of unique token holders.

Parameters:

address (string, required) - Token mint address

Response:

json

{
  "success": true,
  "data": {
    "holders": 847
  }
}

Example:

bash

curl https://api.goonpad.dev/api/tokens/7xKXtg2CW87d97.../holders

POST /tokens/track

Initiates monitoring for a specific token.

Request Body:

json

{
  "address": "7xKXtg2CW87d97...",
  "webhookUrl": "https://your-webhook.com/notify"
}

Note: webhookUrl is optional.

Response:

json

{
  "success": true,
  "data": {
    "trackingId": "track_abc123",
    "address": "7xKXtg2CW87d97...",
    "message": "Token tracking initiated"
  }
}

Example:

bash

curl -X POST https://api.goonpad.dev/api/tokens/track \
  -H "Content-Type: application/json" \
  -d '{"address":"7xKXtg2CW87d97..."}'

Platform Endpoints

GET /platform/stats

Returns platform-wide statistics.

Response:

json

{
  "success": true,
  "data": {
    "totalTokens": 1247,
    "totalVolume": "15234567.89",
    "totalFees": "45123.67",
    "activeTrades": 234
  }
}

Example:

bash

curl https://api.goonpad.dev/api/platform/stats

GET /platform/health

Returns API and RPC connection health status.

Response (Healthy):

json

{
  "success": true,
  "data": {
    "healthy": true,
    "rpcEndpoint": "https://api.devnet.solana.com",
    "latency": 45,
    "timestamp": "2024-01-01T12:00:00.000Z"
  }
}

Response (Unhealthy):

json

{
  "error": "error",
  "data": {
    "healthy": false,
    "rpcEndpoint": "https://api.devnet.solana.com",
    "error": "Connection timeout",
    "timestamp": "2024-01-01T12:00:00.000Z"
  }
}

Status Codes:

200 - Healthy
503 - Service Unavailable (unhealthy)

Example:

bash

curl https://api.goonpad.dev/api/platform/health

GET /platform/nutjar

Returns global Nut Jar balance and statistics.

Response:

json

{
  "success": true,
  "data": {
    "balance": 125.5,
    "totalAccumulated": 340.2,
    "totalClaimed": 214.7,
    "activeTokens": 45
  }
}

Example:

bash

curl https://api.goonpad.dev/api/platform/nutjar

GET /platform/fees/:tokenAddress

Calculate fees for a specific token.

Parameters:

tokenAddress (string, required) - Token mint address

Response:

json

{
  "success": true,
  "data": {
    "tokenAddress": "7xKXtg2CW87d97...",
    "platformFee": 1.5,
    "creatorFee": 0.45,
    "totalFees": 1.95
  }
}

Example:

bash

curl https://api.goonpad.dev/api/platform/fees/7xKXtg2CW87d97...

Upload Endpoints

POST /upload/image

Upload token image to IPFS via Pinata.

Request:

Content-Type: multipart/form-data
Body: Form data with file field containing image

Response:

json

{
  "success": true,
  "uri": "https://gateway.pinata.cloud/ipfs/Qm...",
  "ipfsHash": "Qm...",
  "pinSize": 12345,
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Example:

bash

curl -X POST https://api.goonpad.dev/api/upload/image \
  -F "file=@/path/to/image.png"

POST /upload/metadata

Upload token metadata JSON to IPFS via Pinata.

Request Body:

json

{
  "name": "Goon Coin",
  "symbol": "GOON",
  "description": "The best meme coin",
  "image": "https://gateway.pinata.cloud/ipfs/Qm..."
}

Response:

json

{
  "success": true,
  "uri": "https://gateway.pinata.cloud/ipfs/Qm...",
  "ipfsHash": "Qm...",
  "pinSize": 456,
  "timestamp": "2024-01-01T12:00:00.000Z"
}

Example:

bash

curl -X POST https://api.goonpad.dev/api/upload/metadata \
  -H "Content-Type: application/json" \
  -d '{"name":"Goon Coin","symbol":"GOON","image":"https://..."}'

GET /upload/test

Test Pinata IPFS connection.

Response:

json

{
  "success": true,
  "message": "Pinata connection successful",
  "configured": true
}

Example:

bash

curl https://api.goonpad.dev/api/upload/test

Platform Constants

Useful constants for calculations:

json

{
  "GRADUATION_TARGET_SOL": 85,
  "TRENDING_THRESHOLD_SOL": 70,
  "PLATFORM_FEE_PERCENT": 1.75,
  "CREATOR_FEE_SHARE_PERCENT": 30,
  "TOKEN_EXPIRY_HOURS": 24,
  "TOKEN_DECIMALS": 9
}

Error Responses

All endpoints may return errors:

400 Bad Request

json

{
  "success": false,
  "error": "Invalid token address",
  "message": "Invalid token address"
}

404 Not Found

json

{
  "success": false,
  "error": "Token not found",
  "message": "Token not found"
}

500 Internal Server Error

json

{
  "success": false,
  "error": "Failed to fetch token data",
  "message": "Internal server error"
}

503 Service Unavailable

json

{
  "success": false,
  "error": "RPC connection failed",
  "message": "Service temporarily unavailable"
}

Data Types

Token Object

Field	Type	Required	Description
`address`	string	[x]	Token mint address
`name`	string	⚠️	Token full name
`symbol`	string	⚠️	Token ticker symbol
`decimals`	number	⚠️	Token decimals (usually 9)
`supply`	string	⚠️	Total supply as string
`price`	number	⚠️	Current token price in SOL
`marketCap`	number	⚠️	Market cap in SOL
`volume24h`	number	⚠️	24h trading volume in SOL
`holders`	number	⚠️	Unique holder count
`mint`	string	⚠️	Mint address (same as address)
`poolAddress`	string	⚠️	LaunchLab PoolState account address
`creator`	string	⚠️	Creator wallet address
`createdAt`	number	⚠️	Unix timestamp (seconds)
`graduated`	boolean	⚠️	Whether token graduated to Raydium
`solRaised`	number	⚠️	Total SOL raised in bonding curve
`totalSupply`	number	⚠️	Total supply as number
`pricePerToken`	number	⚠️	Current price per token in SOL
`graduationTarget`	number	⚠️	SOL target for graduation (usually 85)
`bondingCurveProgress`	number	⚠️	Progress (0-1) toward graduation
`tokensRemaining`	number	⚠️	Tokens still available in bonding curve
`imageUrl`	string	⚠️	Token image URL (IPFS)
`pfpImage`	string	⚠️	Creator profile picture URL
`description`	string	⚠️	Token description
`livestreamUrl`	string	⚠️	Livestream URL (if enabled)
`isLive`	boolean	⚠️	Whether livestream is active
`feesClaimed`	boolean	⚠️	Whether creator fees have been claimed

Legend:

[x] = Always present
⚠️ = Optional, may not be present for all tokens

Next Steps

WebSocket API - Real-time updates
Code Examples - Integration examples
Troubleshooting - Common issues

Questions? Check the FAQ or API Overview.

REST API Endpoints

Base URL

Token Endpoints

GET /tokens

GET /tokens/trending

GET /tokens/nutted

GET /tokens/:address

GET /tokens/:address/nutjar

GET /tokens/:address/holders

POST /tokens/track

Platform Endpoints

GET /platform/stats

GET /platform/health

GET /platform/nutjar

GET /platform/fees/:tokenAddress

Upload Endpoints

POST /upload/image

POST /upload/metadata

GET /upload/test

Platform Constants

Error Responses

400 Bad Request

404 Not Found

500 Internal Server Error

503 Service Unavailable

Data Types

Token Object

Next Steps