# Aliases (https://dev.cosmospay.lat/docs/api/aliases/)

> Payment handles: resolve a name to its addresses, and claim or manage one with a signature by each address it points at.

Base URL: `https://api.cosmospay.lat/cosmos-api`

## Resolve an alias to its addresses

`GET /v1/aliases/resolve/{name}`

Answers the addresses of the alias on one chain (Stellar unless `chain` names another), optionally narrowed to one `network`, primary first, with `primaryAddress` as the default to pay (null when it has none there). The name is matched trimmed and lowercased. An unknown or suspended alias is a 404, and nothing about its owner is returned.

Requires the `payments:read` scope. The shared public key may call it.

**Path parameters**

- `name` (string, required)

**Query parameters**

- `network` (string, optional): Limit to one network (public | testnet | a custom id).
- `chain` (string, optional): The chain to resolve on. Omit for Stellar: a wallet that does not ask for a chain is never handed another chain’s address. One of: `stellar`, `solana`, `monad`.

**Responses**

- `200` (`AliasResolutionEntity`): OK
  - `name` (string, required): Normalized handle: the form uniqueness is decided on.
  - `displayName` (string, required): As the claimant typed it. Display only.
  - `chain` (string, required): The chain resolved on: the one asked for, else Stellar. One of: `stellar`, `solana`, `monad`.
  - `addresses` (AliasAddressEntity[], required): Every verified address on the requested chain and network, primary first.
  - `primaryAddress` (object, optional): The address to pay when the payer did not choose one.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Is this handle claimable, and if not why not

`GET /v1/aliases/availability/{name}`

Checks the trimmed, lowercased handle and answers `available`, with a `reason` when it is not: `too_short` or `too_long` (3 to 32 characters), `bad_characters` (a-z, 0-9 and underscores, starting and ending with a letter or digit), `reserved`, `address_like` (it would read as a Stellar address) or `taken`. It reserves nothing: a claim can still lose the name with `409 alias_taken`.

Requires the `payments:read` scope. The shared public key may call it.

**Path parameters**

- `name` (string, required)

**Responses**

- `200` (`AliasAvailabilityEntity`): OK
  - `name` (string, required): The handle as checked: trimmed and lowercased.
  - `available` (boolean, required): Whether the handle can be claimed now.
  - `reason` (object, optional): Why not, when unavailable: taken, reserved, bad_characters, …
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Which aliases point at this address

`GET /v1/aliases/by-address/{address}`

The active aliases holding this address, oldest first, each with its `chain`, `network` and whether the address is its primary there, as `{ data }` (not paged). Without `chain` the chain is read off the address's own shape, and a Monad address matches whatever its letter case. An address no chain accepts answers an empty `data`, not an error.

Requires the `payments:read` scope. The shared public key may call it.

**Path parameters**

- `address` (string, required)

**Query parameters**

- `network` (string, optional): Limit to addresses registered on this network (public | testnet | a custom id). Omit for every network.
- `chain` (string, optional): Omit to read the chain off the address’s own shape. One of: `stellar`, `solana`, `monad`.

**Responses**

- `200` (`AliasByAddressEntity`): OK
  - `data` (AliasByAddressEntryEntity[], required): The active aliases holding the address, oldest first; empty when none does.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Get a nonce to sign

`POST /v1/aliases/challenges`

Returns the EXACT message to digest and sign. Single-use and short-lived; the purpose is inside the signed bytes, so a signature collected to add an address cannot be replayed to complete a recovery.

Requires the `payments:write` scope.

**Request body** (`application/json`, required): `CreateAliasChallengeDto`

- `name` (string, required): The handle being claimed.
- `chain` (string, optional): Chain the address is on. Omit for Stellar. Stellar signs the challenge digest (ed25519); Solana signs the challenge text (ed25519, `signMessage`); Monad signs it with EIP-191 `personal_sign`. One of: `stellar`, `solana`, `monad`.
- `address` (string, required): The address on `chain`: Stellar G…, Solana base58, Monad 0x….
- `network` (string, required): Network id: public | testnet | a custom id.
- `purpose` (string, optional): What the signature will be spent on: CLAIM (a new alias), ADD_ADDRESS (another address on an alias) or RECOVER (finishing an email recovery). Anything but CLAIM needs an existing alias. One of: `CLAIM`, `ADD_ADDRESS`, `RECOVER`.

**Responses**

- `201` (`AliasChallengeEntity`): Created
  - `nonce` (string, required): Send this back with the signature.
  - `message` (string, required): The EXACT string to sign: digested first on Stellar, signed as text on Solana and Monad. Returned rather than described so a client never rebuilds it from prose. A client that assembles the fields itself is one field-order change away from producing signatures nothing accepts.
  - `domain` (string, required): Domain tag the digest is framed with.
  - `purpose` (string, required): What the signature can be spent on: the purpose the request asked for. One of: `CLAIM`, `ADD_ADDRESS`, `RECOVER`.
  - `expiresAt` (string (date-time), required): When the challenge stops being spendable (ISO 8601 date-time), 5 minutes after it was issued.
- `400` (`ApiErrorBodyEntity`): `validation_failed`: The body, query or headers failed validation `alias_name_invalid`: Reserved, malformed, or the wrong length
  - `statusCode` (number, required): Always the HTTP status of the response itself.
  - `code` (string, required): Stable machine-readable code. Branch on this, never on the message: messages are human-facing and may be reworded; codes are never renamed once published. Each response documents the subset it can return. One of: `insufficient_scope`, `no_authenticated_consumer`, `gateway_required`, `admin_console_only`, `not_found`, `validation_failed`, `payload_too_large`, `idempotency_conflict`, `operation_in_flight`, `invalid_state_transition`, `slippage_exceeded`, `insufficient_balance`, `no_path_found`, `trustline_missing`, `invalid_amount`, `invalid_memo`, `transaction_rejected`, `transaction_already_settled`, `recipient_not_registered`, `payment_transfer_mismatch`, `fee_transfer_mismatch`, `merchant_fee_transfer_mismatch`, `payer_mismatch`, `transaction_not_found`, `expired`, `network_unsupported`, `asset_unsupported`, `merchant_fee_unsupported`, `provider_error`, `provider_unavailable`, `quote_not_found`, `quote_expired`, `kyc_state_invalid`, `kyc_review_required`, `account_disabled`, `payload_expired`, `rate_limited`, `customer_wallet_taken`, `alias_taken`, `alias_name_invalid`, `alias_challenge_invalid`, `alias_signature_invalid`, `alias_recovery_invalid`, `alias_address_conflict`, `wallet_handshake_invalid`, `wallet_verifier_invalid`, `wallet_login_code_invalid`, `wallet_login_code_cooldown`, `wallet_session_invalid`, `wallet_signature_invalid`, `wallet_backup_invalid`, `wallet_backup_limit`, `wallet_account_mismatch`, `wallet_provider_unavailable`, `wallet_return_url_not_allowed`, `wallet_recovery_setup_refused`, `easy_recovery_not_found`, `easy_recovery_already_offered`, `easy_recovery_not_offered`, `easy_recovery_code_invalid`, `easy_recovery_burned`, `plugin_not_installed`, `plugin_consent_mismatch`, `plugin_rejected`, `plugin_quota_exceeded`, `plugin_failed`, `protected_payment_buyer_mismatch`, `protected_payment_signature_invalid`, `misconfigured`, `internal_error`.
  - `error` (string, required): The HTTP reason phrase for `statusCode`.
  - `message` (string | string[], required): Human-readable detail. An array when class-validator rejected the body.
  - `details` (object, optional): Machine-readable facts about this failure, present only on the codes whose example shows it: `easy_recovery_code_invalid` carries `{ "attemptsLeft": 4 }`. Absent everywhere else.
  - `path` (string, required): The path of the request that failed.
  - `timestamp` (string, required): When the envelope was produced, ISO 8601.
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## List the caller's aliases

`GET /v1/aliases`

The aliases this consumer holds, newest first, each with its recovery `email`, `status` and every address on every chain and network (primary first). Paged with `take` (default and maximum 50) and `skip`; answers `{ data, total, take, skip }`.

Requires the `payments:read` scope.

**Query parameters**

- `take` (number, optional): Page size: how many aliases to return, at most 50.
- `skip` (number, optional): How many aliases to skip before this page.

**Responses**

- `200` (`AliasListEntity`): OK
  - `data` (OwnedAliasEntity[], required): The aliases on this page, newest first.
  - `total` (number, required): How many aliases the caller holds, across all pages.
  - `take` (number, required): The page size this page was read with.
  - `skip` (number, required): How many aliases were skipped before this page.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `500`: InternalError (see Shared responses)

## Claim an alias with a signature

`POST /v1/aliases`

Takes the `nonce` of a `CLAIM` challenge from `POST /v1/aliases/challenges` and the signature over its message: the address, chain and network registered are the challenge's, never the body's, and that address becomes the alias's primary. A challenge is single-use and lives 5 minutes (`alias_challenge_invalid`); a signature that does not verify is `alias_signature_invalid`. `email` is the mailbox recovery goes to, a consumer holds at most 25 aliases (`400 alias_address_conflict`) and the first claim of a name wins (`409 alias_taken`).

Requires the `payments:write` scope.

**Request body** (`application/json`, required): `ClaimAliasDto`

- `name` (string, required): The handle being claimed: the one the challenge was issued for.
- `email` (string, required): Recovery mailbox. Required at claim time, not later: an alias whose owner loses their key before adding one is unrecoverable, and that is the state this field exists to prevent.
- `nonce` (string, required): The nonce from POST /v1/aliases/challenges.
- `signature` (string, required): Stellar: base64 ed25519 over the challenge digest. Solana: base64 or base58 ed25519 over the challenge text. Monad: 0x-hex EIP-191 signature over the challenge text.
- `label` (string, optional): Human label for this first address.

**Responses**

- `201` (`OwnedAliasEntity`): Created
  - `id` (string, required): The alias id.
  - `name` (string, required): Normalized handle: the form uniqueness is decided on.
  - `displayName` (string, required): As the claimant typed it. Display only.
  - `status` (string, required): SUSPENDED when an operator holds the alias (an impersonation report, a dispute): a suspended alias does not resolve. One of: `ACTIVE`, `SUSPENDED`.
  - `addresses` (AliasAddressEntity[], required): Every address of the alias, on every chain and network, primary first.
  - `createdAt` (string (date-time), required): When the alias was claimed (ISO 8601 date-time).
  - `email` (string, required): The recovery mailbox, trimmed and lowercased.
  - `emailVerifiedAt` (object, optional): When the recovery mailbox was verified (ISO 8601 date-time); null while it is not.
- `400` (`ApiErrorBodyEntity`): `validation_failed`: The body, query or headers failed validation `alias_name_invalid`: Reserved, malformed, or the wrong length `alias_challenge_invalid`: No challenge, expired, already spent, or issued for other details `alias_signature_invalid`: The signature does not verify against the claiming address `alias_address_conflict`: The address is already on the alias, or the alias is at its cap
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `409` (`ApiErrorBodyEntity`): `alias_taken`: someone claimed the handle first. There is no queue and no reservation: pick another name.
- `500`: InternalError (see Shared responses)

## Point the alias at another address

`POST /v1/aliases/{name}/addresses`

Needs two proofs: the caller owns the alias, and the NEW address signs for itself. One alias may hold many addresses across many networks.

Requires the `payments:write` scope.

**Path parameters**

- `name` (string, required)

**Request body** (`application/json`, required): `AddAliasAddressDto`

- `chain` (string, optional): Chain the address is on. Omit for Stellar. Stellar signs the challenge digest (ed25519); Solana signs the challenge text (ed25519, `signMessage`); Monad signs it with EIP-191 `personal_sign`. One of: `stellar`, `solana`, `monad`.
- `address` (string, required): The address on `chain`: Stellar G…, Solana base58, Monad 0x….
- `network` (string, required): Network id the address is on (public | testnet | a custom id); it must be the challenge's.
- `nonce` (string, required): The nonce from an ADD_ADDRESS challenge.
- `signature` (string, required): Stellar: base64 ed25519 over the challenge digest. Solana: base64 or base58 ed25519 over the challenge text. Monad: 0x-hex EIP-191 signature over the challenge text.
- `label` (string, optional): Human label for this address.
- `primary` (boolean, optional): Make this the address a payer gets when they do not ask for a specific one on this network. Exactly one address per network is primary.

**Responses**

- `201` (`AliasAddressEntity`): Created
  - `id` (string, required): The id of this address on the alias, as `DELETE /v1/aliases/{name}/addresses/{addressId}` takes it.
  - `chain` (string, required): The chain the address is on. One of: `stellar`, `solana`, `monad`.
  - `address` (string, required): On `chain`: Stellar G…, Solana base58, Monad 0x… (EIP-55).
  - `network` (string, required): Network id the address is on: public | testnet | a custom id.
  - `label` (object, optional): Human label the owner gave this address; null without one.
  - `isPrimary` (boolean, required): The default for this chain and network.
  - `verifiedAt` (string (date-time), required): When this address proved control of itself.
- `400` (`ApiErrorBodyEntity`): `validation_failed`: The body, query or headers failed validation `alias_challenge_invalid`: No challenge, expired, already spent, or issued for other details `alias_signature_invalid`: The signature does not verify against the claiming address `alias_address_conflict`: The address is already on the alias, or the alias is at its cap
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Remove one address from the alias

`DELETE /v1/aliases/{name}/addresses/{addressId}`

Deletes one address of an alias this consumer holds. When it was the primary on its chain and network, the oldest remaining address there becomes primary. The last address of the alias cannot be removed: release the alias instead.

Requires the `payments:write` scope.

**Path parameters**

- `name` (string, required)
- `addressId` (string, required)

**Responses**

- `200` (`AliasDeletedEntity`): OK
  - `id` (string, required): The id of what was deleted: the alias on a release, the address on an address removal.
  - `deleted` (boolean, required): Always true.
- `400` (`ApiErrorBodyEntity`): `alias_address_conflict`: an alias must keep at least one address. Release the alias instead.
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Release the alias back to the namespace

`DELETE /v1/aliases/{name}`

Deletes an alias this consumer holds, with all its addresses, so anyone can claim the name again. An alias held by another consumer is a 404.

Requires the `payments:write` scope.

**Path parameters**

- `name` (string, required)

**Responses**

- `200` (`AliasDeletedEntity`): OK
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Start email recovery: the token is emailed to the owner

`POST /v1/aliases/{name}/recovery`

Always `{ accepted: true }`, whether or not the alias exists and the mailbox matched: a handle is public and the mailbox behind it is not. When both match, the token is emailed to the mailbox on record (at most once a minute per alias); it never appears in the response.

Requires the `payments:write` scope. The shared public key may call it.

**Path parameters**

- `name` (string, required)

**Request body** (`application/json`, required): `StartAliasRecoveryDto`

- `email` (string, required): The mailbox on record. Checked but never echoed: the response is identical whether or not it matched, so this endpoint cannot be used to ask which address owns a handle.

**Responses**

- `201` (`AliasRecoveryStartedEntity`): Created
  - `accepted` (boolean, required): Always true, whether or not anything matched. The token, when there is one, is emailed to the mailbox on record, never returned here.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `503` (`ApiErrorBodyEntity`): `misconfigured`: A server-side configuration error: retrying will not help

## Finish recovery: take ownership with a new address

`POST /v1/aliases/{name}/recovery/complete`

Needs the emailed token AND a signature from the new key. Every previous address is dropped: recovery exists because the old keys are gone, and leaving them resolvable would keep whoever holds them receiving payments.

Requires the `payments:write` scope.

**Path parameters**

- `name` (string, required)

**Request body** (`application/json`, required): `CompleteAliasRecoveryDto`

- `token` (string, required): The token delivered by email.
- `chain` (string, optional): Chain the address is on. Omit for Stellar. Stellar signs the challenge digest (ed25519); Solana signs the challenge text (ed25519, `signMessage`); Monad signs it with EIP-191 `personal_sign`. One of: `stellar`, `solana`, `monad`.
- `address` (string, required): The address that will own the alias from now on, on `chain`: Stellar G…, Solana base58, Monad 0x….
- `network` (string, required): Network id the new address is on (public | testnet | a custom id); it must be the challenge's.
- `nonce` (string, required): The nonce from a RECOVER challenge.
- `signature` (string, required): Stellar: base64 ed25519 over the challenge digest. Solana: base64 or base58 ed25519 over the challenge text. Monad: 0x-hex EIP-191 signature over the challenge text.

**Responses**

- `200` (`OwnedAliasEntity`): OK
- `400` (`ApiErrorBodyEntity`): `validation_failed`: The body, query or headers failed validation `alias_recovery_invalid`: The recovery token is unknown, expired or already spent `alias_signature_invalid`: The signature does not verify against the claiming address `alias_address_conflict`: The address is already on the alias, or the alias is at its cap
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)

## Shared responses

- **ValidationFailed** (`ApiErrorBodyEntity`): The body, query or path failed validation. `message` is an array of the individual failures. Routes that reject a *valid* request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
- **Unauthorized** (`ApiErrorBodyEntity`): `no_authenticated_consumer`: The gateway forwarded no API key identity
- **Forbidden** (`ApiErrorBodyEntity`): `insufficient_scope`: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked `x-cosmos-public-key`, with a message saying so; more scopes will not help, the key is the wrong one. `gateway_required`: the request did not arrive through APISIX.
- **NotFound** (`ApiErrorBodyEntity`): No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
- **InternalError** (`ApiErrorBodyEntity`): Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
- **RateLimited** (`ApiErrorBodyEntity`): The budget in `x-cosmos-rate-limit` is spent for this caller. Honour `Retry-After`. The `ratelimit-*` triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers `503 provider_unavailable`.
