Skip to main content
Four tools manage Veil usernames. A @handle lets others send offramps directly to you without seeing your bank details. See 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
​
string
required
Handle to check, without the @ prefix.
Outputs
​
boolean
required
true if the handle is free to claim.
​
string
Explanation when available is false (e.g. taken, invalid format, reserved).
Example

​
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
​
string
required
Handle to claim, without the @ prefix.
Outputs
​
string
required
claimed on success. taken if the handle was taken. step_up_required if re-verification is needed. error on other failures.
​
string
Canonical form of the claimed handle.
​
string
Display form including the @ prefix.
​
string
ISO 8601 timestamp when the handle was claimed.
​
string
Error description on failure.
Example

​
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
​
string
required
New handle to claim, without the @ prefix.
Outputs
​
string
required
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.
​
string
New canonical handle.
​
string
New display handle.
​
string
The handle that was replaced.
​
string
When the new handle was claimed.
​
string
When the cooldown expires. Present when status is cooldown.
​
string
Error description on failure.
Example

​
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
​
string
required
Recipient’s handle, with or without the @ prefix.
Outputs
​
string
required
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.
​
string
The recipient’s display handle.
​
string
When the security hold ends. Present when status is cooldown.
​
string
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.
​
string
Error or explanatory message on non-ready statuses.
Example

​
See also

  • Usernames — handle routing and the recipient model
  • Offramp tools — using beneficiaryUsername and bindingToken in quotes and executes