> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useveil.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Username tools
> Claim and manage your @handle, and preview recipients before sending.
Four tools manage Veil usernames. A `@handle` lets others send offramps directly to you without seeing your bank details. See [Usernames](/concepts/usernames) for the full concept.
***
### veil\_username\_check
Check whether a handle is available for claiming. Use this before `veil_username_claim` to avoid a failed attempt.
**Inputs**
Handle to check, without the `@` prefix.
**Outputs**
`true` if the handle is free to claim.
Explanation when `available` is false (e.g. taken, invalid format, reserved).
**Example**
```dialog theme={null}
[calls veil_username_check with username="alice"]
→ available: true
```
***
### veil\_username\_claim
Claim a permanent `@handle`. Handles are 3–30 characters: letters, digits, and underscores only.
Requires a recent email verification (a successful `veil_verify_otp` within the last 10 minutes). If `status` is `step_up_required`, ask the user to verify their email and retry.
**Inputs**
Handle to claim, without the `@` prefix.
**Outputs**
`claimed` on success. `taken` if the handle was taken. `step_up_required` if re-verification is needed. `error` on other failures.
Canonical form of the claimed handle.
Display form including the `@` prefix.
ISO 8601 timestamp when the handle was claimed.
Error description on failure.
**Example**
```dialog theme={null}
[calls veil_username_claim with username="alice"]
→ status: "claimed", username: "alice", displayUsername: "@alice",
claimedAt: "2026-05-14T12:00:00Z"
```
***
### veil\_username\_rename
Rename your `@handle`. The old handle is released and the new one is claimed atomically. Subject to a cooldown after each rename.
Requires a recent email verification. Returns `status: step_up_required` if re-verification is needed.
**Inputs**
New handle to claim, without the `@` prefix.
**Outputs**
`renamed` on success. `taken` if the new handle is taken. `cooldown` if the rename cooldown is active. `step_up_required` if re-verification is needed. `error` on other failures.
New canonical handle.
New display handle.
The handle that was replaced.
When the new handle was claimed.
When the cooldown expires. Present when `status` is `cooldown`.
Error description on failure.
**Example**
```dialog theme={null}
[calls veil_username_rename with username="bob"]
→ status: "renamed", username: "bob", displayUsername: "@bob", previousUsername: "alice"
```
***
### veil\_username\_beneficiary\_preview
Resolve a `@handle` to a recipient's bank account and check if they are ready to receive offramps. Call this before quoting or executing a send-to-handle offramp.
When `status` is `ready`, the response includes a `bindingHint` containing a short-lived binding token. Pass that token to `veil_offramp_quote` and `veil_offramp_execute` as `bindingToken` to lock in the recipient and prevent drift between preview and execute.
**Inputs**
Recipient's handle, with or without the `@` prefix.
**Outputs**
`ready` when the recipient can receive offramps. `not_ready` if they haven't completed onboarding. `cooldown` if their bank account is on a security hold. `not_found` if the handle doesn't exist. `self` if you look up your own handle. `error` on other failures.
The recipient's display handle.
When the security hold ends. Present when `status` is `cooldown`.
Instruction that includes the binding token value. Present when `status` is `ready`. Pass the token to `veil_offramp_quote` and `veil_offramp_execute` as `bindingToken`.
Error or explanatory message on non-ready statuses.
**Example**
```dialog theme={null}
[calls veil_username_beneficiary_preview with handle="alice"]
→ status: "ready", displayUsername: "@alice",
bindingHint: "Use bindingToken=\"eyJ...\" in veil_offramp_quote and veil_offramp_execute..."
```
## See also
* [Usernames](/concepts/usernames) — handle routing and the recipient model
* [Offramp tools](/mcp/tools/offramp) — using `beneficiaryUsername` and `bindingToken` in quotes and executes