/wallet/lookup

Returns the Claimr address and balance for a Twitter handle.

Request

GET /api/wallet/lookup?handle=elonmusk

The @ prefix is optional.

Response

{
  "handle": "elonmusk",
  "twitterId": "44196397",
  "address": "7HbxHbUMZRVCkh2f8YSvXkzLygwjL1vgHEFpHQP8qyEn",
  "balance": {
    "pda": "5.2000",
    "vault": "3.1000",
    "total": "8.3000"
  },
  "totalWithdrawn": "10.5000",
  "canWithdraw": true,
  "withdrawPreview": {
    "gross": "8.3000",
    "fee": "0.1660",
    "net": "8.1340"
  },
  "profile": {
    "name": "Elon Musk",
    "profileImageUrl": "https://pbs.twimg.com/...",
    "verified": true,
    "followersCount": 234547321
  }
}

When canWithdraw is false, the response includes a reason field and withdrawPreview is null:

{
  "canWithdraw": false,
  "withdrawPreview": null,
  "reason": "Minimum withdrawal is 0.04 SOL"
}

Response Fields

Field	Description
handle	Normalized Twitter handle
twitterId	Numeric Twitter ID (required for /collect calls)
address	Claimr PDA address (use as creator address on Pump.fun)
balance.pda	Available for withdrawal
balance.vault	Requires collection before withdrawal
balance.total	Combined PDA and vault balance
totalWithdrawn	Lifetime withdrawal total for this handle
canWithdraw	true if total balance >= 0.04 SOL
withdrawPreview	Projected withdrawal amounts after fees (null if below minimum)
reason	Explanation when canWithdraw is false (omitted otherwise)
profile.name	Display name
profile.profileImageUrl	Avatar URL
profile.verified	Verification status
profile.followersCount	Follower count

Errors

Code	Description
HANDLE_REQUIRED	No handle parameter provided
INVALID_HANDLE	Invalid Twitter handle format
TWITTER_NOT_FOUND	Twitter account does not exist