> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# list_codes

> List the user's promo (coupon) codes: every code they have redeemed or attempted, with its amount and state — used (credit already sent), awaiting_verification…

Connect to `https://mcp.agentcard.sh/mcp` with the **user's connection token** (or a `buy_token` for org-owned accounts).

**Behavior:** read-only, idempotent.

<Note>Not in the default `tools/list`. It is still callable by exact name, and appears when the client sends the `x-expert-tools: 1` header.</Note>

## What it does

List the user's promo (coupon) codes: every code they have redeemed or attempted, with its amount and state — used (credit already sent), awaiting\_verification (claimed and reserved; pays out automatically once the user passes KYC — offer start\_kyc), processing (mid-transfer), available (a failed attempt they can retry with redeem\_code), or expired. Codes the user has never presented cannot be listed; they only enter the history via redeem\_code.

## Inputs

None.

## Returns

| Field                  | Type   | Description                                                     |
| ---------------------- | ------ | --------------------------------------------------------------- |
| `message` *(required)* | string | Human-readable list of the user's codes (or a "no codes" note). |
| `count`                | number | Number of codes returned.                                       |
| `codes`                | array  | The user's promo-code history, newest first.                    |

## Example call

```json theme={null}
{
  "tool": "list_codes",
  "arguments": {}
}
```