Wallet Sign-in
The Cosmos Pay Wallet’s own sign-in: Authentik (OpenID Connect), Google, GitHub or an emailed code. It proves who a person is and never touches a key; the seed backup it stores is sealed on the device under a password this service never sees.
Render buttons from this rather than from a compiled-in list. A deployment with no Google credentials should not show a Google button that dies at the consent screen.
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>.
OK
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/wallet/auth/providers'{ "providers": [ "authentik", "google", "github" ], "sources": [ { "id": "google", "name": "Google" } ], "email": true, "mfaSettingsUrl": "https://auth.example.com/if/user/#/settings;{\"page\":\"page-credentials\"}"}Returns the URL to open in a browser. Keep the PKCE verifier on the device: the state travels through the browser and buys only polling, while the verifier is what redeems the handshake.
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>.
application/json- body
Starts an OAuth (PKCE) wallet sign-in with an identity provider.
provider*stringThe identity provider to sign in with.
"authentik""google""github"codeChallenge*stringbase64url(SHA-256(verifier)), RFC 7636 S256. Keep the verifier on the device: it is what makes a state seen in a browser worthless to anyone else, and it is the only thing that can redeem this handshake.
codeChallengeMethod*"S256"RFC 7636 S256, the only method accepted. Declared rather than ignored: the wallet sends it, and an undeclared field is a 400 under forbidNonWhitelisted. Pinned rather than defaulted, because plain is the one value that would make the verifier no secret at all.
"S256"returnTo?stringA native wallet’s own URL: a custom scheme, a universal/app link, or http://127.0.0.1:<port>/… from a desktop app. When set, the callback answers 302 to it with ?state=… (plus &error=<reason> on failure) instead of rendering a page, which is what closes the platform’s auth session. Must be listed in the deployment’s WALLET_AUTH_RETURN_URLS (a loopback entry matches any port). Only the state travels: the handshake is still redeemed with the verifier.
source?stringStart at one of Authentik’s sources (Google, GitHub…) instead of its login page: an id from sources on GET /v1/wallet/auth/providers, with provider: authentik. The browser goes straight to that provider and comes back through Authentik, so the handshake and its ID token are the same as any Authentik sign-in. Send it only to a deployment that listed it: an older one refuses the unknown field.
OK
wallet_provider_unavailable: That provider is unknown, or not configured on this deployment
wallet_return_url_not_allowed: The return URL is not one this deployment redirects to
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.
wallet_provider_unavailable: That provider is unknown, or not configured on this deployment
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/wallet/auth/oauth/authorize' \ -H 'Content-Type: application/json' \ -d '{ "provider": "google", "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "codeChallengeMethod": "S256"}'{ "state": "string", "authorizationUrl": "string", "expiresAt": "2019-08-24T14:15:22Z"}Not called by your code: the person’s browser lands here. Public by necessity: a navigation carries no API key and no gateway consumer. It renders a page (or, when the handshake was opened with a returnTo, redirects to it with the state) and nothing else; the identity is collected by the device that holds the PKCE verifier. Register {WALLET_AUTH_PUBLIC_BASE_URL}/v1/wallet/auth/oauth/callback/{provider} with each provider.
provider*string"authentik""google""github"error?unknownSent by the provider when the person declined or the authorization failed. Any value ends a pending handshake denied, and no code is exchanged.
state?unknownThe handshake's state, as POST /v1/wallet/auth/oauth/authorize answered it. Missing, unknown, for another provider, no longer pending or past its expiry: the callback reports expired and changes nothing.
code?unknownThe authorization code the provider issued, which this service exchanges with the provider for the person's identity. Missing, a pending handshake ends denied.
A "you can go back to your wallet" page. It never contains the identity or a token.
The handshake was opened with a returnTo: the browser is sent there with ?state=…, plus &error=<reason> when the sign-in did not succeed. The same reason tokens the poll reports; never the identity.
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 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/wallet/auth/oauth/callback/authentik'"string"Answers on the state alone, and never returns the identity at any status. Poll until it leaves pending, then redeem with the verifier.
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>.
state*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.
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 GET 'https://api.cosmospay.lat/cosmos-api/v1/wallet/auth/oauth/session/string'{ "status": "pending", "error": "denied", "bound": true}A NEW email ends here, with a session token. An email that ALREADY has an account gets verify_email instead and a code in its inbox: a provider proves who consented, not who opened the sign-in, and an existing account is where the backup worth stealing is. An Authentik email the provider has not confirmed also gets verify_email, account or not, under the same per-address cooldown as email/start. The exception is a sign-in through Authentik’s emailed link (the email source), whose ID token carries cosmos_inbox_proven: true: that login already proved the inbox, so an existing account ends here too, with its backups and the idToken.
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>.
application/json- body
Redeems a finished OAuth sign-in handshake with its PKCE verifier.
state*stringThe handshake handle, from /oauth/authorize.
codeVerifier*stringThe PKCE verifier this device kept. Never sent anywhere else, and never stored by this service.
purpose?stringrecovery when the proven identity is going to be presented to the SEP-30 recovery servers. It always routes through an emailed code, even for an email with no account, and only then does the answer carry the provider's idToken: a provider proves who consented, not who opened the sign-in, and a recovery identity is worth a wallet. The one exception is an existing account signed in through Authentik’s emailed link (cosmos_inbox_proven: true in its ID token), which already proved the inbox.
"sign-in""sign-in""recovery"binding?stringThe device binding: the one-time value the callback put in the fragment of its redirect to the wallet’s return URL, after an Authentik emailed sign-in (the poll says bound). Only with it does that sign-in skip the code for an existing account. Send it only when the poll said bound: an older server refuses the unknown field.
OK
wallet_verifier_invalid: The PKCE verifier does not match the handshake
wallet_login_code_cooldown: Another code was sent to this mailbox moments ago
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/wallet/auth/oauth/claim' \ -H 'Content-Type: application/json' \ -d '{ "state": "string", "codeVerifier": "string"}'{ "status": "ready", "identity": { "email": "someone@example.com", "name": {}, "avatar": {}, "method": "authentik" }, "account": "existing", "backups": [ { "chain": "stellar", "address": "string", "stellarAddress": "string", "box": "string", "updatedAt": "string" } ], "backup": { "chain": "stellar", "address": "string", "stellarAddress": "string", "box": "string", "updatedAt": "string" }, "sessionToken": "string", "expiresInSeconds": 1800, "idToken": "string"}Emails a six-digit code to email, valid 15 minutes (expiresInSeconds), and answers a claimToken naming that code; send both to POST /v1/wallet/auth/email/verify. One mailbox gets at most one code a minute and 10 in 24 hours, whoever asks: more is 400 wallet_login_code_cooldown. Only SHA-256 hashes of the code and the claim token are stored.
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>.
application/json- body
Starts a wallet sign-in by emailed code.
email*stringThe email address to send the six-digit code to.
OK
wallet_login_code_cooldown: Another code was sent to this mailbox moments ago
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/wallet/auth/email/start' \ -H 'Content-Type: application/json' \ -d '{ "email": "someone@example.com"}'{ "claimToken": "string", "expiresInSeconds": 900}Wrong codes are counted on the row, not by the client. Five burns it, and a burned code is replaced by asking for another.
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>.
application/json- body
Answers an emailed sign-in code.
claimToken*stringThe claim token returned by /auth/email/start.
code*stringThe six digits emailed.
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.
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/wallet/auth/email/verify' \ -H 'Content-Type: application/json' \ -d '{ "claimToken": "string", "code": "048213"}'{ "status": "ready", "identity": { "email": "someone@example.com", "name": {}, "avatar": {}, "method": "authentik" }, "account": "existing", "backups": [ { "chain": "stellar", "address": "string", "stellarAddress": "string", "box": "string", "updatedAt": "string" } ], "backup": { "chain": "stellar", "address": "string", "stellarAddress": "string", "box": "string", "updatedAt": "string" }, "sessionToken": "string", "expiresInSeconds": 1800, "idToken": "string"}Send the session token as X-Wallet-Session: {sessionToken}. The gateway strips Authorization. The signature covers exactly:
Cosmos Pay Wallet sign-inemail: {lowercased email}account: {address}at: {signedAt}signed over those raw UTF-8 bytes with the account key, base64. The first line is one no Stellar transaction envelope can begin with, which is what makes signing it safe.
On Solana and Monad (chain), a chain: {chain} line follows the first one. Solana signs the bytes with ed25519 (signMessage; base64 or base58); Monad with EIP-191 personal_sign (0x-hex).
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>.
X-Wallet-Session*string{sessionToken}, from the sign-in that just finished. Authorization: Bearer {sessionToken} is read too, but only on a direct call: APISIX strips it.
application/json- body
Finishes a wallet sign-in: the wallet's signature over the sign-in challenge, and optionally its backup. The session token travels in X-Wallet-Session.
chain?stringChain the account is on. Omit for Stellar. Solana signs the challenge with ed25519 over its UTF-8 bytes; Monad with EIP-191 personal_sign.
"stellar""stellar""solana""monad"address?stringThe account on chain: Stellar G…, Solana base58, Monad 0x…. Send this or stellarAddress, not both.
stellarAddress?stringDeprecatedThe Stellar account (the field’s original name, still accepted for Stellar). New clients send address.
signedAt*stringWhen the challenge was signed: an ISO 8601 instant in UTC (Z), at most millisecond precision; it must be close to the server's clock.
signature*stringSignature over the sign-in challenge: base64 ed25519 on Stellar, base64 or base58 ed25519 on Solana, 0x-hex EIP-191 on Monad. The exact bytes are documented on the operation; a client that rebuilds them from prose is one field-order change away from producing signatures nothing accepts.
backup?stringThe device's sealed seed box, to keep for the next device: one per (chain, address), up to 20 per account. Opaque here: it is sealed under a key derived from a password this service never sees.
replaceBackup?booleanAccepted for older wallets and ignored. Backups are kept per wallet: a box for another address is added beside the ones the account keeps, and a box for the same wallet replaces its own. Nothing is ever discarded to make room.
falsenetwork?stringThe ledger the account's signers are read from (a recovered account's key signs for it on the ledger it was re-keyed on). Omit for the default.
"public""testnet"OK
wallet_signature_invalid: The signature does not verify, or its timestamp is out of window
wallet_backup_invalid: Not a backup box this service will keep
wallet_backup_limit: The account already keeps as many wallet backups as it may
wallet_session_invalid: The sign-in token is missing, expired, or was not minted here
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.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/wallet/auth/finish' \ -H 'X-Wallet-Session: string' \ -H 'Content-Type: application/json' \ -d '{ "signedAt": "2026-01-02T03:04:05Z", "signature": "string"}'{ "status": "ready", "account": "created", "organizationId": "string", "keys": { "dev": {}, "prod": {} }}What changePassword on the device sends. No session: the signature is the credential, and it covers the SHA-256 of the box, so one signature stores exactly one box and cannot be replayed to store another. The bytes are:
Cosmos Pay Wallet backupaccount: {address}box: {sha256 hex of box}at: {signedAt}On Solana and Monad a chain: {chain} line follows the first one, and the bytes are signed as for sign-in.
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>.
application/json- body
Replaces the sealed backup box of one of the account's wallets, signed by that wallet.
chain?stringChain the account is on. Omit for Stellar. Solana signs the challenge with ed25519 over its UTF-8 bytes; Monad with EIP-191 personal_sign.
"stellar""stellar""solana""monad"address?stringThe account on chain: Stellar G…, Solana base58, Monad 0x…. Send this or stellarAddress, not both.
stellarAddress?stringDeprecatedThe Stellar account (the field’s original name, still accepted for Stellar). New clients send address.
box*stringThe re-sealed box. Opaque to this service.
signedAt*stringWhen the challenge was signed: an ISO 8601 instant in UTC (Z), at most millisecond precision; it must be close to the server's clock.
signature*stringSignature over the backup challenge (encoded as for sign-in), which covers the box's SHA-256, so one signature stores exactly one box.
network?stringThe ledger the account's signers are read from (a recovered account's key signs for it on the ledger it was re-keyed on). Omit for the default.
"public""testnet"OK
wallet_signature_invalid: The signature does not verify, or its timestamp is out of window
wallet_backup_invalid: Not a backup box this service will keep
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.
wallet_account_mismatch: No backup is stored for the account that signed
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.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
curl -X PUT 'https://api.cosmospay.lat/cosmos-api/v1/wallet/backup' \ -H 'Content-Type: application/json' \ -d '{ "box": "string", "signedAt": "2026-01-02T03:04:05Z", "signature": "string"}'{ "status": "ok", "chain": "stellar", "address": "string", "stellarAddress": "string", "updatedAt": "2019-08-24T14:15:22Z"}Send the session token as X-Wallet-Session: {sessionToken}. The gateway strips Authorization. The signature covers exactly:
Cosmos Pay Wallet recovery setupaccount: {stellarAddress}signers: {signerA},{signerB}at: {signedAt}The envelope comes back signed by the sponsor only. Once per account: refused when the account already has a signer besides its master key.
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>.
X-Wallet-Session*string{sessionToken}. Authorization: Bearer {sessionToken} is read too, but only on a direct call: APISIX strips it.
application/json- body
Asks the operator to sponsor the reserve of an account's two recovery signers.
stellarAddress*stringThe Stellar account (G...) to set the recovery signers on.
signers*array<string>The two recovery servers' signers for this account, in role order.
signedAt*stringWhen the challenge was signed: an ISO 8601 instant in UTC (Z), at most millisecond precision; it must be close to the server's clock.
signature*stringbase64 ed25519 signature over the recovery-setup challenge.
network?stringThe ledger the account's signers are read from (a recovered account's key signs for it on the ledger it was re-keyed on). Omit for the default.
"public""testnet"OK
wallet_signature_invalid: The signature does not verify, or its timestamp is out of window
wallet_session_invalid: The sign-in token is missing, expired, or was not minted here
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.
wallet_recovery_setup_refused: The account cannot be sponsored: missing, or already has signers
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.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/wallet/recovery/setup' \ -H 'X-Wallet-Session: string' \ -H 'Content-Type: application/json' \ -d '{ "stellarAddress": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN", "signers": [ "string" ], "signedAt": "2026-01-02T03:04:05Z", "signature": "string"}'{ "transaction": "string", "sponsor": "string", "network_passphrase": "string"}KYC wallets and bank accounts
A receiver's blockchain wallets and fiat bank accounts, the bank rails and the fields each rail asks for.
Account Recovery (SEP-10 / SEP-30)
Served by the two recovery deployments only. Standard SEP-10 web authentication and SEP-30 account recovery: each server holds half of what a recovery signature needs, and proves the person’s inbox on its own.