Followers

GET /followers

List all tracked followers with pagination and filtering.

Request

GET /followers?status=launched&limit=50&offset=0

Query Parameters

Parameter	Type	Default	Description
status	string	-	Filter by status
limit	number	50	Results per page (max 100)
offset	number	0	Skip N results

Status Values

Status	Description
pending	Waiting to launch
processing	Launch in progress
launched	Successfully launched
failed	Launch failed
skipped	Backfilled/skipped

Response

{
  "followers": [
    {
      "id": "abc-123-def",
      "username": "cryptofan",
      "displayName": "Crypto Fan",
      "status": "launched",
      "tokenName": "WP_CRYPTOFAN",
      "tokenSymbol": "WCRYPTOFAN",
      "tokenAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "pumpUrl": "https://pump.fun/7xKXtg...",
      "detectedAt": "2024-01-15T11:55:00.000Z",
      "launchedAt": "2024-01-15T11:55:30.000Z",
      "retryCount": 0,
      "errorMessage": null
    }
  ],
  "pagination": {
    "total": 1542,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Response Fields

Follower Object

Field	Type	Description
id	string	Unique identifier
username	string	X username
displayName	string?	X display name
status	string	Launch status
tokenName	string?	Token name
tokenSymbol	string?	Token symbol
tokenAddress	string?	Solana address
pumpUrl	string?	pump.fun URL
detectedAt	string	Detection timestamp
launchedAt	string?	Launch timestamp
retryCount	number	Retry attempts
errorMessage	string?	Last error

Pagination Object

Field	Type	Description
total	number	Total matching records
limit	number	Requested limit
offset	number	Current offset
hasMore	boolean	More results available?

Examples

Get All Followers

curl "http://localhost:3000/followers"

Get Launched Only

curl "http://localhost:3000/followers?status=launched"

Get Failed (for retry)

curl "http://localhost:3000/followers?status=failed"

Paginate Results

1

Page 1

curl "http://localhost:3000/followers?limit=20&offset=0"

2

Page 2

curl "http://localhost:3000/followers?limit=20&offset=20"

3

Page 3

curl "http://localhost:3000/followers?limit=20&offset=40"

---

GET /followers/:id

Get detailed information about a specific follower, including audit logs.

Request

GET /followers/:id

Path Parameters

Parameter	Type	Description
id	string	Follower UUID

Response

{
  "follower": {
    "id": "abc-123-def",
    "username": "cryptofan",
    "displayName": "Crypto Fan",
    "profileUrl": "https://x.com/cryptofan",
    "avatarUrl": "https://pbs.twimg.com/...",
    "twitterId": "123456789",
    "detectedAt": "2024-01-15T11:55:00.000Z",
    "status": "launched",
    "launchedAt": "2024-01-15T11:55:30.000Z",
    "tokenAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "tokenName": "WP_CRYPTOFAN",
    "tokenSymbol": "WCRYPTOFAN",
    "metadataUri": "ipfs://QmXxx...",
    "txSignature": "5Uj8vWX2...",
    "pumpUrl": "https://pump.fun/7xKXtg...",
    "errorMessage": null,
    "retryCount": 0,
    "lastRetryAt": null,
    "createdAt": "2024-01-15T11:55:00.000Z",
    "updatedAt": "2024-01-15T11:55:30.000Z",
    "logs": [
      {
        "id": "log-123",
        "action": "LAUNCH_SUCCESS",
        "details": {
          "tokenAddress": "7xKXtg...",
          "signature": "5Uj8...",
          "pumpUrl": "https://pump.fun/7xKXtg..."
        },
        "createdAt": "2024-01-15T11:55:30.000Z"
      },
      {
        "id": "log-122",
        "action": "TX_SUBMITTED",
        "details": { "mint": "7xKXtg..." },
        "createdAt": "2024-01-15T11:55:25.000Z"
      },
      {
        "id": "log-121",
        "action": "IPFS_UPLOADED",
        "details": { "uri": "ipfs://QmXxx..." },
        "createdAt": "2024-01-15T11:55:15.000Z"
      },
      {
        "id": "log-120",
        "action": "LAUNCH_STARTED",
        "details": null,
        "createdAt": "2024-01-15T11:55:05.000Z"
      },
      {
        "id": "log-119",
        "action": "DETECTED",
        "details": { "displayName": "Crypto Fan" },
        "createdAt": "2024-01-15T11:55:00.000Z"
      }
    ]
  }
}

Error Response (404)

{
  "error": true,
  "message": "Follower not found"
}

Example

curl http://localhost:3000/followers/abc-123-def | jq

Use Cases

• View launch details - Full token info and transaction

• Debug failures - See error message and logs

• Audit trail - Complete history of actions

• Verify launches - Check token address and signature

---

Filtering Examples

Find All Pending

curl "http://localhost:3000/followers?status=pending" | jq '.followers[].username'

Find Retryable Failures

curl "http://localhost:3000/followers?status=failed" | jq '.followers[] | select(.retryCount < 3)'

Get Recent Launches

curl "http://localhost:3000/followers?status=launched&limit=10" | jq '.followers[] | {username, tokenSymbol, launchedAt}'

Count by Status

1

Total launched

curl -s "http://localhost:3000/followers?status=launched&limit=1" | jq '.pagination.total'

2

Total failed

curl -s "http://localhost:3000/followers?status=failed&limit=1" | jq '.pagination.total'