API Reference

Aliases

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

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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

name*string
network?string

Limit to one network (public | testnet | a custom id).

chain?string

The chain to resolve on. Omit for Stellar: a wallet that does not ask for a chain is never handed another chain’s address.

Value in"stellar""solana""monad"

OK

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.

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/aliases/resolve/string'
Example Response
{  "name": "string",  "displayName": "string",  "chain": "stellar",  "addresses": [    {      "id": "string",      "chain": "stellar",      "address": "string",      "network": "public",      "label": {},      "isPrimary": true,      "verifiedAt": "2019-08-24T14:15:22Z"    }  ],  "primaryAddress": {}}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

name*string

OK

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.

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/aliases/availability/string'
Example Response
{  "name": "string",  "available": true,  "reason": {}}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

address*string
network?string

Limit to addresses registered on this network (public | testnet | a custom id). Omit for every network.

chain?string

Omit to read the chain off the address’s own shape.

Value in"stellar""solana""monad"

OK

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.

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/aliases/by-address/string'
Example Response
{  "data": [    {      "name": "alice",      "displayName": "Alice",      "chain": "stellar",      "network": "public",      "isPrimary": true    }  ]}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

application/json
  1. body

Request for a single-use challenge to sign: the handle, the address that will sign, its network and what the signature is for.

name*string

The handle being claimed.

chain?string

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.

Default"stellar"
Value in"stellar""solana""monad"
address*string

The address on chain: Stellar G…, Solana base58, Monad 0x….

network*string

Network id: public | testnet | a custom id.

purpose?string

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.

Default"CLAIM"
Value in"CLAIM""ADD_ADDRESS""RECOVER"

Created

validation_failed: The body, query or headers failed validation

alias_name_invalid: Reserved, malformed, or the wrong length

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/aliases/challenges' \  -H 'Content-Type: application/json' \  -d '{  "name": "emanuel250",  "address": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",  "network": "public"}'
Example Response
{  "nonce": "string",  "message": "string",  "domain": "string",  "purpose": "CLAIM",  "expiresAt": "2019-08-24T14:15:22Z"}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

take?number

Page size: how many aliases to return, at most 50.

Default50
skip?number

How many aliases to skip before this page.

Default0

OK

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.

no_authenticated_consumer: The gateway forwarded no API key identity

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/aliases'
Example Response
{  "data": [    {      "id": "string",      "name": "string",      "displayName": "string",      "status": "ACTIVE",      "addresses": [        {          "id": "string",          "chain": "stellar",          "address": "string",          "network": "public",          "label": {},          "isPrimary": true,          "verifiedAt": "2019-08-24T14:15:22Z"        }      ],      "createdAt": "2019-08-24T14:15:22Z",      "email": "someone@example.com",      "emailVerifiedAt": {}    }  ],  "total": 0,  "take": 0,  "skip": 0}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

application/json
  1. body

Request to claim an alias with a signature over a CLAIM challenge. The address, chain and network registered are the challenge's.

name*string

The handle being claimed: the one the challenge was issued for.

email*string

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

The nonce from POST /v1/aliases/challenges.

signature*string

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

Human label for this first address.

Created

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

no_authenticated_consumer: The gateway forwarded no API key identity

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.

alias_taken: someone claimed the handle first. There is no queue and no reservation: pick another name.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/aliases' \  -H 'Content-Type: application/json' \  -d '{  "name": "emanuel250",  "email": "someone@example.com",  "nonce": "string",  "signature": "string"}'
Example Response
{  "id": "string",  "name": "string",  "displayName": "string",  "status": "ACTIVE",  "addresses": [    {      "id": "string",      "chain": "stellar",      "address": "string",      "network": "public",      "label": {},      "isPrimary": true,      "verifiedAt": "2019-08-24T14:15:22Z"    }  ],  "createdAt": "2019-08-24T14:15:22Z",  "email": "someone@example.com",  "emailVerifiedAt": {}}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

name*string
application/json
  1. body

Request to add another address to an alias the caller holds, with that address's signature over an ADD_ADDRESS challenge.

chain?string

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.

Default"stellar"
Value in"stellar""solana""monad"
address*string

The address on chain: Stellar G…, Solana base58, Monad 0x….

network*string

Network id the address is on (public | testnet | a custom id); it must be the challenge's.

nonce*string

The nonce from an ADD_ADDRESS challenge.

signature*string

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

Human label for this address.

primary?boolean

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.

Defaultfalse

Created

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

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/aliases/string/addresses' \  -H 'Content-Type: application/json' \  -d '{  "address": "string",  "network": "testnet",  "nonce": "string",  "signature": "string"}'
Example Response
{  "id": "string",  "chain": "stellar",  "address": "string",  "network": "public",  "label": {},  "isPrimary": true,  "verifiedAt": "2019-08-24T14:15:22Z"}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

name*string
addressId*string

OK

alias_address_conflict: an alias must keep at least one address. Release the alias instead.

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/aliases/string/addresses/string'
Example Response
{  "id": "string",  "deleted": true}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

name*string

OK

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.

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/aliases/string'
Example Response
{  "id": "string",  "deleted": true}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

name*string
application/json
  1. body

Request to start an alias's email recovery: when the mailbox matches, the token is emailed to it.

email*string

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.

Created

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.

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

misconfigured: A server-side configuration error: retrying will not help

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/aliases/string/recovery' \  -H 'Content-Type: application/json' \  -d '{  "email": "someone@example.com"}'
Example Response
{  "accepted": true}
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.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

name*string
application/json
  1. body

Request to finish an email recovery: the emailed token and a signature over a RECOVER challenge by the address that takes ownership.

token*string

The token delivered by email.

chain?string

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.

Default"stellar"
Value in"stellar""solana""monad"
address*string

The address that will own the alias from now on, on chain: Stellar G…, Solana base58, Monad 0x….

network*string

Network id the new address is on (public | testnet | a custom id); it must be the challenge's.

nonce*string

The nonce from a RECOVER challenge.

signature*string

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.

OK

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

no_authenticated_consumer: The gateway forwarded no API key identity

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.

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.

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.

Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/aliases/string/recovery/complete' \  -H 'Content-Type: application/json' \  -d '{  "token": "string",  "address": "string",  "network": "public",  "nonce": "string",  "signature": "string"}'
Example Response
{  "id": "string",  "name": "string",  "displayName": "string",  "status": "ACTIVE",  "addresses": [    {      "id": "string",      "chain": "stellar",      "address": "string",      "network": "public",      "label": {},      "isPrimary": true,      "verifiedAt": "2019-08-24T14:15:22Z"    }  ],  "createdAt": "2019-08-24T14:15:22Z",  "email": "someone@example.com",  "emailVerifiedAt": {}}