Aliases
Payment handles: resolve a name to its addresses, and claim or manage one with a signature by each address it points at.
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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
name*stringnetwork?stringLimit to one network (public | testnet | a custom id).
chain?stringThe chain to resolve on. Omit for Stellar: a wallet that does not ask for a chain is never handed another chain’s address.
"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.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/aliases/resolve/string'{ "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": {}}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
name*stringOK
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.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/aliases/availability/string'{ "name": "string", "available": true, "reason": {}}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
address*stringnetwork?stringLimit to addresses registered on this network (public | testnet | a custom id). Omit for every network.
chain?stringOmit to read the chain off the address’s own shape.
"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.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/aliases/by-address/string'{ "data": [ { "name": "alice", "displayName": "Alice", "chain": "stellar", "network": "public", "isPrimary": true } ]}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
application/json- 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*stringThe handle being claimed.
chain?stringChain 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.
"stellar""stellar""solana""monad"address*stringThe address on chain: Stellar G…, Solana base58, Monad 0x….
network*stringNetwork id: public | testnet | a custom id.
purpose?stringWhat 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.
"CLAIM""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.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/aliases/challenges' \ -H 'Content-Type: application/json' \ -d '{ "name": "emanuel250", "address": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN", "network": "public"}'{ "nonce": "string", "message": "string", "domain": "string", "purpose": "CLAIM", "expiresAt": "2019-08-24T14:15:22Z"}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
take?numberPage size: how many aliases to return, at most 50.
50skip?numberHow many aliases to skip before this page.
0OK
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.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/aliases'{ "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}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
application/json- body
Request to claim an alias with a signature over a CLAIM challenge. The address, chain and network registered are the challenge's.
name*stringThe handle being claimed: the one the challenge was issued for.
email*stringRecovery 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*stringThe nonce from POST /v1/aliases/challenges.
signature*stringStellar: 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?stringHuman 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.
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"}'{ "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": {}}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
name*stringapplication/json- body
Request to add another address to an alias the caller holds, with that address's signature over an ADD_ADDRESS challenge.
chain?stringChain 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.
"stellar""stellar""solana""monad"address*stringThe address on chain: Stellar G…, Solana base58, Monad 0x….
network*stringNetwork id the address is on (public | testnet | a custom id); it must be the challenge's.
nonce*stringThe nonce from an ADD_ADDRESS challenge.
signature*stringStellar: 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?stringHuman label for this address.
primary?booleanMake 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.
falseCreated
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.
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"}'{ "id": "string", "chain": "stellar", "address": "string", "network": "public", "label": {}, "isPrimary": true, "verifiedAt": "2019-08-24T14:15:22Z"}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
name*stringaddressId*stringOK
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.
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/aliases/string/addresses/string'{ "id": "string", "deleted": true}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
name*stringOK
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.
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/aliases/string'{ "id": "string", "deleted": true}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
name*stringapplication/json- body
Request to start an alias's email recovery: when the mailbox matches, the token is emailed to it.
email*stringThe 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
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/aliases/string/recovery' \ -H 'Content-Type: application/json' \ -d '{ "email": "someone@example.com"}'{ "accepted": true}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
name*stringapplication/json- body
Request to finish an email recovery: the emailed token and a signature over a RECOVER challenge by the address that takes ownership.
token*stringThe token delivered by email.
chain?stringChain 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.
"stellar""stellar""solana""monad"address*stringThe address that will own the alias from now on, on chain: Stellar G…, Solana base58, Monad 0x….
network*stringNetwork id the new address is on (public | testnet | a custom id); it must be the challenge's.
nonce*stringThe nonce from a RECOVER challenge.
signature*stringStellar: 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.
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"}'{ "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": {}}