Wallet Status API

Check Bullpen account membership and current campaign-token eligibility for a Solana wallet.

Projects can use this endpoint to compare an existing token-holder list with Bullpen account membership. It also checks whether the supplied address meets the currently configured campaign-token threshold.

No authentication is required. Send one Solana wallet address per request.

The endpoint is built for on-demand lookups and occasional batch runs. It is not a continuous feed.

Request

GET https://usergate.bullpen.fi/api/wallet/bullpen-status?address=<solana_wallet_address>

Parameter	Required	Description
address	Yes	A valid Solana wallet address.

Example

curl "https://usergate.bullpen.fi/api/wallet/bullpen-status?address=CSmiPfwEoKFCrtyG8u6nSj28dNsox3mwVhtoCEgiTo8K"

Response

{
  "isBullpenWallet": true,
  "holdsAnsem": true,
  "holdsAnsemStatus": "confirmed"
}

Field	Type	Meaning
isBullpenWallet	boolean	true when the address belongs to a Bullpen account.
holdsAnsem	boolean or null	true or false when the token balance is confirmed. null when the balance could not be confirmed.
holdsAnsemStatus	string	Explains whether holdsAnsem is authoritative.

Status values

Values are lowercase on the wire.

Value	Meaning	How to treat holdsAnsem
confirmed	The onchain balance read succeeded.	Authoritative.
unavailable	The onchain balance read failed.	Unknown. Retry later.
unconfigured	No campaign or eligibility token is configured.	Unknown.

The status list can grow. Treat an unrecognized value as not confirmed.

Integration rules

1. isBullpenWallet: true means the address is attached to a Bullpen account. Imported wallets count, not only wallets generated through Bullpen.
2. The endpoint accepts Solana addresses only. An Ethereum-style 0x address returns HTTP 400.
3. A malformed address returns HTTP 400. A valid-format non-wallet address does not. Token mints, program IDs, and token accounts can parse as Solana addresses and return isBullpenWallet: false. Submit wallet addresses only.
4. unavailable is not a negative holder result. It means the chain read could not be completed.
5. Partner projects supply their own holder lists. The endpoint does not return or enumerate Bullpen wallets.

Rate limits

The public tier allows approximately 10 requests per second per IP, with a burst capacity of 20. This limit is shared with other public endpoints. There is no per-partner API key or quota.

A few thousand addresses is fine for an occasional batch. At a steady 10 requests per second, 5,000 addresses takes roughly 8 to 10 minutes. Back off after HTTP 429 before retrying.

Results are cached server-side. Repeat runs are cheaper, and negative results are cached longer than positive results.

Current campaign token

The endpoint checks one globally configured campaign token. The current token is $ANSEM. Every caller receives a result for that same token.

Changing the campaign token is a configuration update. The endpoint cannot check several project tokens at once.

Staging

Staging intentionally has no eligibility token configured. It returns holdsAnsem: null with holdsAnsemStatus: "unconfigured". Production returns live holder results.