API Reference

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.

GET
/.well-known/stellar.toml

WEB_AUTH_ENDPOINT and SIGNING_KEY (SEP-10), HOME_DOMAIN, and a [[RECOVERY_SERVERS]] entry with the SEP-30 ENDPOINT, the ROLE and the identity methods. 404 on a deployment that is not a recovery server.

network?string

The ledger the file describes, public or testnet: its SEP-10 and SEP-30 endpoints then carry that ledger as a path segment. Omit for the deployment default. Any other value, or a ledger not in RECOVERY_NETWORKS, is a 404.

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.

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/.well-known/stellar.toml'
Example Response
"string"
GET
/v1/sep10/auth

Public: no API key. Answers a SEP-10 challenge transaction for account (a G... address) with the network_passphrase to sign it for; sign it with the account and exchange it at POST /v1/sep10/auth. Sequence 0: unsubmittable by construction. Errors have the SEP body { "error": "..." }; a deployment that is not a recovery server answers 404.

account*string

The Stellar account (G…) to authenticate.

200

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.

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 GET 'https://api.cosmospay.lat/cosmos-api/v1/sep10/auth?account=string'
Example Response
Empty
POST
/v1/sep10/auth

Weighed against the account's CURRENT signers and medium threshold, so a recovered account authenticates with the key that replaced its master.

application/json
  1. body

SEP-10: the signed challenge transaction, exchanged for a token of that account.

transaction*string

The challenge, signed by the account.

200

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.

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.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/sep10/auth' \  -H 'Content-Type: application/json' \  -d '{  "transaction": "string"}'
Example Response
Empty
POST
/v1/sep30/identity

SEP-30 "external" authentication. The ID token is verified against the provider's published keys, must stand for a login in the last 15 minutes, must carry a VERIFIED email, and is accepted once per server.

application/json
  1. body

Proves an inbox to this recovery server with an OIDC ID token.

id_token*string

An OIDC ID token from the provider this server names as OIDC_ISSUER in its stellar.toml. Accepted once per server.

200

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.

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/sep30/identity' \  -H 'Content-Type: application/json' \  -d '{  "id_token": "string"}'
Example Response
Empty
POST
/v1/sep30/identity/email/start

The same answer whether or not the address recovers anything here; a code is only sent to one that does.

application/json
  1. body

Asks this recovery server to email a code that proves an inbox.

email*string

The inbox to prove.

200

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.

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/sep30/identity/email/start' \  -H 'Content-Type: application/json' \  -d '{  "email": "person@example.com"}'
Example Response
Empty
POST
/v1/sep30/identity/email/verify

Public: no API key. Send the claim_token from POST /v1/sep30/identity/email/start with the emailed code: the right answer is status: ready with this server's identity token for that inbox, once; a wrong one is invalid with attempts_left, and an unknown, used or lapsed claim is expired. Five wrong answers burn it (locked).

application/json
  1. body

Answers the code this recovery server emailed.

claim_token*string

The claim_token from POST /v1/sep30/identity/email/start (base64url).

code*string

The six digits emailed.

200

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.

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/sep30/identity/email/verify' \  -H 'Content-Type: application/json' \  -d '{  "claim_token": "string",  "code": "123456"}'
Example Response
Empty
GET
/v1/sep30/accounts

A SEP-10 token lists its own account when it is registered here; this server's identity token for an email lists every account naming that email. It reads one ledger (the one the path names, e.g. /v1/sep30/testnet/accounts, or the default) and answers up to 100 accounts per page in address order as { accounts }; pass the last address as after for the next page. Errors have the SEP body { "error": "..." }: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

sep-token
headerAuthorizationBearer <JWT>

A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.

after?string

The last address of the previous page.

200

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.

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 GET 'https://api.cosmospay.lat/cosmos-api/v1/sep30/accounts'
Example Response
Empty
GET
/v1/sep30/accounts/{address}

The account's identity roles, flagging the one the token authenticates as, and this server's signer key for it. Takes the account's SEP-10 token, or this server's identity token for an email registered on it; an account that is absent and one the token may not act on are the same 404. Errors have the SEP body { "error": "..." }: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

sep-token
headerAuthorizationBearer <JWT>

A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.

200

OK

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 GET 'https://api.cosmospay.lat/cosmos-api/v1/sep30/accounts/{address}'
Example Response
Empty
POST
/v1/sep30/accounts/{address}

Stores who may recover address (1 to 3 identities, roles owner, sender or receiver, each with 1 to 3 email auth methods) and answers the account with signers: this server's key for it. Only a SEP-10 token of that same account may call it (403 otherwise), and an account already registered here is a 409: change it with PUT. Errors have the SEP body { "error": "..." }: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

sep-token
headerAuthorizationBearer <JWT>

A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.

application/json
  1. body

SEP-30: the identities that may recover an account.

identities*array<>

The account's identities.

200

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 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/sep30/accounts/{address}' \  -H 'Content-Type: application/json' \  -d '{  "identities": [    {      "role": "owner",      "auth_methods": [        {          "type": "email",          "value": "person@example.com"        }      ]    }  ]}'
Example Response
Empty
DELETE
/v1/sep30/accounts/{address}

Deletes the registration and its identities and answers the account as it was. Only a SEP-10 token of that same account may call it (403 otherwise); an account not registered here is a 404. Errors have the SEP body { "error": "..." }: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

sep-token
headerAuthorizationBearer <JWT>

A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.

200

OK

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 DELETE 'https://api.cosmospay.lat/cosmos-api/v1/sep30/accounts/{address}'
Example Response
Empty
PUT
/v1/sep30/accounts/{address}

Replaces the identities of address, never merging them with the old ones, and registers the account if it is not here yet. Only a SEP-10 token of that same account may call it (403 otherwise); it answers the account as POST does. Errors have the SEP body { "error": "..." }: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

sep-token
headerAuthorizationBearer <JWT>

A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.

application/json
  1. body

SEP-30: the identities that may recover an account.

identities*array<>

The account's identities.

200

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 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 PUT 'https://api.cosmospay.lat/cosmos-api/v1/sep30/accounts/{address}' \  -H 'Content-Type: application/json' \  -d '{  "identities": [    {      "role": "owner",      "auth_methods": [        {          "type": "email",          "value": "person@example.com"        }      ]    }  ]}'
Example Response
Empty
POST
/v1/sep30/accounts/{address}/sign/{signer}

Returns the SIGNATURE, not an envelope. Only an account-control change on the registered account, sourced by it, with no memo, valid for at most 15 minutes.

sep-token
headerAuthorizationBearer <JWT>

A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.

application/json
  1. body

SEP-30: a transaction for this server to co-sign for a recovered account.

transaction*string

The transaction to co-sign, base64 XDR.

200

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 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/sep30/accounts/{address}/sign/{signer}' \  -H 'Content-Type: application/json' \  -d '{  "transaction": "string"}'
Example Response
Empty
GET
/v1/sep30/shares

This server's identity token for an email. One proof brings back the halves of every wallet backed up under it.

sep-token
headerAuthorizationBearer <JWT>

A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.

after?string

The last address of the previous page.

200

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.

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 GET 'https://api.cosmospay.lat/cosmos-api/v1/sep30/shares'
Example Response
Empty
GET
/v1/sep30/shares/{address}

The account's SEP-10 token, or this server's identity token for the email the half was filed under. Absent and not-yours are the same 404.

sep-token
headerAuthorizationBearer <JWT>

A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.

200

OK

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 GET 'https://api.cosmospay.lat/cosmos-api/v1/sep30/shares/{address}'
Example Response
Empty
DELETE
/v1/sep30/shares/{address}

Deletes this server's half of the backup recovery key filed for address and answers { address }. Only a SEP-10 token of that same account may call it (403 otherwise); no half filed here is a 404. Errors have the SEP body { "error": "..." }: 401 without a valid token from this server, 404 on a deployment that is not a recovery server.

sep-token
headerAuthorizationBearer <JWT>

A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.

200

OK

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 DELETE 'https://api.cosmospay.lat/cosmos-api/v1/sep30/shares/{address}'
Example Response
Empty
PUT
/v1/sep30/shares/{address}

Replaces any half filed before: a re-sealed backup has a new key. The email is who may take the half back.

sep-token
headerAuthorizationBearer <JWT>

A token from THIS recovery server: POST /v1/sep10/auth (the account's key) or POST /v1/sep30/identity / /identity/email/verify (an inbox). The sibling server never accepts it.

application/json
  1. body

This server's half of a wallet backup's recovery key, filed under the inbox that may take it back.

share*string

This server's half of the backup's recovery key: 32 random-looking bytes, base64. Useless without the other server's half.

email*string

The inbox that may take the half back, proven to THIS server with its identity token.

200

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 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 PUT 'https://api.cosmospay.lat/cosmos-api/v1/sep30/shares/{address}' \  -H 'Content-Type: application/json' \  -d '{  "share": "q83vEjRWeJCrze8SNFZ4kKvN7xI0VniQq83vEjRWeJA=",  "email": "person@example.com"}'
Example Response
Empty