WebSocket API

Real-time updates for prices, trades, and token events via Socket.io WebSocket.

Connection

WebSocket URL

https://api.goonpad.dev

Installation

For Node.js:

npm install socket.io-client

For Browser:

<script src="https://cdn.socket.io/4.5.4/socket.io.min.js"></script>

Basic Connection

import { io } from 'socket.io-client'

const socket = io('https://api.goonpad.dev', {
  transports: ['websocket', 'polling'],
  reconnection: true,
  reconnectionDelay: 1000,
  reconnectionAttempts: 5
})

socket.on('connect', () => {
  console.log('✅ Connected to GoonPad WebSocket')
  console.log('Socket ID:', socket.id)
})

socket.on('disconnect', () => {
  console.log('🔌 Disconnected from WebSocket')
})

socket.on('connect_error', (error) => {
  console.error('❌ Connection error:', error)
})

Available Channels

Subscribe to channels to receive real-time updates:

Channel	Description
tokens	All token updates (price, market cap, etc.)
token:ADDRESS	Updates for a specific token
platform	Platform-wide statistics
nutjar	Nut Jar accumulation events
feed:live	Live activity feed (buys, sells, launches)
feed:edging	Tokens approaching graduation

Event Types

tokens:update

Emitted when token data changes (price, market cap, holders, etc.).

socket.on('tokens:update', (data) => {
  console.log('Token update:', data)
})

Response:

{
  "success": true,
  "data": [
    {
      "tokenAddress": "7xKXtg2CW87d97...",
      "marketCap": 42.5,
      "price": 0.0000425,
      "bondingCurveProgress": 0.5,
      "graduated": false,
      "holders": 847,
      "lastUpdate": "2024-01-01T12:00:00Z"
    }
  ],
  "timestamp": "2024-01-01T12:00:00.000Z"
}

feed:live:update

Emitted for all platform activity (launches, buys, sells, graduations).

socket.on('feed:live:update', (event) => {
  console.log('Live event:', event)
})

Response (Buy/Sell):

{
  "id": "event_abc123",
  "user": "9YzW...3yG",
  "userFull": "9YzWk8vJVh3yG...",
  "action": "bought",
  "amount": "1.5",
  "token": "$GOON",
  "tokenAddress": "7xKXtg2CW87d97...",
  "time": "just now",
  "timestamp": 1704067200
}

Response (Graduation):

{
  "id": "event_xyz789",
  "user": "9YzW...3yG",
  "userFull": "9YzWk8vJVh3yG...",
  "action": "graduated",
  "token": "$GOON",
  "tokenAddress": "7xKXtg2CW87d97...",
  "time": "just now",
  "timestamp": 1704067200
}

token:ADDRESS:update

Emitted when a specific token changes.

const tokenAddress = '7xKXtg2CW87d97...'
socket.on(`token:${tokenAddress}:update`, (data) => {
  console.log('Token specific update:', data)
})

Response:

{
  "success": true,
  "data": {
    "tokenAddress": "7xKXtg2CW87d97...",
    "lastBuy": 1.5,
    "lastSell": 0.8,
    "lastUpdate": 1704067200
  },
  "timestamp": "2024-01-01T12:00:00.000Z"
}

platform:update

Emitted when platform statistics change.

socket.on('platform:update', (stats) => {
  console.log('Platform stats:', stats)
})

Response:

{
  "success": true,
  "data": {
    "totalTokens": 1247,
    "totalVolume24h": 15234.5,
    "graduatedTokens": 89,
    "activeTraders": 3421
  },
  "timestamp": "2024-01-01T12:00:00.000Z"
}

nutjar:update

Emitted when Nut Jar accumulation changes.

socket.on('nutjar:update', (data) => {
  console.log('Nut Jar update:', data)
})

feed:edging:update

Emitted when tokens approach graduation (70-85 SOL).

socket.on('feed:edging:update', (data) => {
  console.log('Edging update:', data)
})

Response:

{
  "token": "$GOON",
  "tokenAddress": "7xKXtg2CW87d97...",
  "currentProgress": 78.5,
  "targetProgress": 85,
  "percentageComplete": 92.35,
  "timestamp": 1704067200
}

Subscribing to Channels

Subscribe to All Tokens

socket.emit('subscribe', 'tokens')

socket.on('tokens:update', (data) => {
  console.log('Tokens updated:', data.data)
})

Subscribe to Specific Token

const tokenAddress = '7xKXtg2CW87d97...'
socket.emit('subscribe', `token:${tokenAddress}`)

socket.on(`token:${tokenAddress}:update`, (data) => {
  console.log(`${tokenAddress} updated:`, data)
})

Subscribe to Live Feed

socket.emit('subscribe', 'feed:live')

socket.on('feed:live:update', (event) => {
  if (event.action === 'bought') {
    console.log(`${event.user} bought ${event.amount} SOL of ${event.token}`)
  } else if (event.action === 'graduated') {
    console.log(`🎉 ${event.token} graduated!`)
  }
})

Subscribe to Multiple Channels

socket.emit('subscribe', 'tokens')
socket.emit('subscribe', 'feed:live')
socket.emit('subscribe', 'platform')

Unsubscribe

socket.emit('unsubscribe', 'tokens')
socket.emit('unsubscribe', 'feed:live')

Complete Example

import { io } from 'socket.io-client'

class GoonPadWebSocket {
  constructor() {
    this.socket = null
  }

  connect() {
    this.socket = io('https://api.goonpad.dev', {
      transports: ['websocket', 'polling'],
      reconnection: true,
      reconnectionDelay: 1000
    })

    this.socket.on('connect', () => {
      console.log('✅ Connected')
      this.subscribeToAll()
    })

    this.socket.on('disconnect', () => {
      console.log('🔌 Disconnected')
    })

    this.setupEventHandlers()
  }

  subscribeToAll() {
    this.socket.emit('subscribe', 'tokens')
    this.socket.emit('subscribe', 'feed:live')
    this.socket.emit('subscribe', 'platform')
  }

  setupEventHandlers() {
    // Token updates
    this.socket.on('tokens:update', (data) => {
      console.log('💰 Token updates:', data.data.length)
    })

    // Live feed
    this.socket.on('feed:live:update', (event) => {
      if (event.action === 'bought') {
        console.log(`🟢 ${event.user} bought ${event.amount} SOL`)
      } else if (event.action === 'sold') {
        console.log(`🔴 ${event.user} sold ${event.amount} SOL`)
      } else if (event.action === 'graduated') {
        console.log(`🎉 ${event.token} graduated!`)
      } else if (event.action === 'launched') {
        console.log(`🚀 New token: ${event.token}`)
      }
    })

    // Platform stats
    this.socket.on('platform:update', (stats) => {
      console.log('📊 Platform stats:', stats.data)
    })

    // Edging feed
    this.socket.on('feed:edging:update', (data) => {
      console.log(`⏫ ${data.token} at ${data.percentageComplete.toFixed(1)}%`)
    })
  }

  subscribeToToken(tokenAddress) {
    this.socket.emit('subscribe', `token:${tokenAddress}`)

    this.socket.on(`token:${tokenAddress}:update`, (data) => {
      console.log(`Token ${tokenAddress} update:`, data)
    })
  }

  disconnect() {
    if (this.socket) {
      this.socket.disconnect()
    }
  }
}

// Usage
const goonpad = new GoonPadWebSocket()
goonpad.connect()

// Subscribe to specific token
setTimeout(() => {
  goonpad.subscribeToToken('YOUR_TOKEN_ADDRESS')
}, 1000)

Heartbeat / Ping

Socket.io handles ping/pong automatically. Default intervals:

• Ping Interval: 25 seconds
• Ping Timeout: 60 seconds

You don't need to manually send pings.

Reconnection

Socket.io handles reconnection automatically with exponential backoff:

const socket = io('https://api.goonpad.dev', {
  reconnection: true,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 5000,
  reconnectionAttempts: Infinity
})

socket.on('reconnect', (attemptNumber) => {
  console.log(`Reconnected after ${attemptNumber} attempts`)
})

socket.on('reconnect_attempt', (attemptNumber) => {
  console.log(`Reconnection attempt ${attemptNumber}`)
})

socket.on('reconnect_error', (error) => {
  console.error('Reconnection error:', error)
})

Rate Limiting

No rate limits on WebSocket connections.

Fair use policy:

• Max 1 connection per client
• Don't spam subscribe/unsubscribe
• Handle messages efficiently

Next Steps

• REST Endpoints - HTTP API reference
• Code Examples - More integration examples
• Troubleshooting - Common issues

---

Start building real-time features!