> For the complete documentation index, see [llms.txt](https://docs.bullpen.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bullpen.fi/developers/wallet-status-api.md).

# 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

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

| Parameter | Required | Description                    |
| --------- | -------- | ------------------------------ |
| `address` | Yes      | A valid Solana wallet address. |

#### Example

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

### Response

```json
{
  "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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bullpen.fi/developers/wallet-status-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.