Yield vaults
Yield vaults on Stellar: discover vaults, read a balance, and build the unsigned deposit or withdrawal the account signs before it is submitted.
The yield vaults on the key's network (a prod key reads mainnet, a dev key testnet), with the vault protocol's answer passed through as is. vault failures are 502 provider_error, and a deployment without a vault API key answers 503 misconfigured.
Requires the liquidity:read or swaps:read scope.
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.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
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 GET 'https://api.cosmospay.lat/cosmos-api/v1/defindex/vaults'One vault's details from the vault protocol on the key's network, passed through as is; vault is its contract address (C...). vault failures are 502 provider_error, and a deployment without a vault API key answers 503 misconfigured.
Requires the liquidity:read or swaps:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
vault*stringThe vault's contract address (C...).
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.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
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 GET 'https://api.cosmospay.lat/cosmos-api/v1/defindex/vaults/string'account's shares and their underlying value in the vault, read from the vault protocol on the key's network and passed through as is. vault failures are 502 provider_error, and a deployment without a vault API key answers 503 misconfigured.
Requires the liquidity:read or swaps:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
vault*stringThe vault's contract address (C...).
account*stringThe Stellar account (G...) whose shares and their underlying value are read.
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.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
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 GET 'https://api.cosmospay.lat/cosmos-api/v1/defindex/vaults/string/balance?account=string'The vault protocol builds the deposit of amounts (integer strings in minor units, at most 9007199254740991 each) into the vault for caller on the key's network; invest defaults to true and slippageBps to 100. The returned XDR is checked to be exactly that call and recorded for this key for up to 15 minutes (less if its time bounds close sooner): sign it unchanged and send it to POST /v1/defindex/submit.
Requires the liquidity:write or swaps:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
vault*stringThe vault's contract address (C...).
application/json- body
Request to build an unsigned deposit into a yield vault for caller, to sign unchanged and send to POST /v1/defindex/submit.
amounts*array<string>One per vault asset, in the asset's minor units: non-negative integer strings no larger than 9007199254740991.
caller*stringThe Stellar account (G...) that deposits: the source of the built transaction, and the account that signs it.
invest?booleanForwarded to the vault protocol as the invest argument of the vault's deposit call.
trueslippageBps?numberSlippage tolerance in basis points (100 = 1%): how far below amounts the deposit's minimum amounts may be.
0 <= value <= 10000100Created
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.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
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/defindex/vaults/string/deposit' \ -H 'Content-Type: application/json' \ -d '{ "amounts": [ "10000000" ], "caller": "string"}'{ "xdr": "AAAAAgAAAAB…", "functionName": "deposit", "params": [ null ], "simulationResponse": {}}The vault protocol builds the burn of shares (an integer string, at most 9007199254740991) for the vault's underlying assets, for caller on the key's network; slippageBps defaults to 100. The returned XDR is checked to be exactly that call and recorded for this key for up to 15 minutes (less if its time bounds close sooner): sign it unchanged and send it to POST /v1/defindex/submit.
Requires the liquidity:write or swaps:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
vault*stringThe vault's contract address (C...).
application/json- body
Request to build an unsigned withdrawal from a yield vault that burns caller's shares for the vault's underlying assets, to sign unchanged and send to POST /v1/defindex/submit.
shares*stringVault shares to burn: a non-negative integer string no larger than 9007199254740991.
caller*stringThe Stellar account (G...) whose shares are burned: the source of the built transaction, and the account that signs it.
slippageBps?numberSlippage tolerance in basis points (100 = 1%), passed to the vault protocol for the withdrawal's minimum outputs.
0 <= value <= 10000100Created
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.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
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/defindex/vaults/string/withdraw' \ -H 'Content-Type: application/json' \ -d '{ "shares": "1000000", "caller": "string"}'{ "xdr": "AAAAAgAAAAB…", "functionName": "deposit", "params": [ null ], "simulationResponse": {}}Relays xdr through the vault protocol only when it is a signed copy of a transaction that POST /v1/defindex/vaults/{vault}/deposit or /withdraw built for this same API key on its network, before it expires; anything else is refused before the vault protocol is called. Relayed once: the vault protocol's answer is stored, and submitting the same transaction again answers it without calling the vault protocol. When the vault protocol gives no answer (502, 503) the same transaction may be submitted again.
Requires the liquidity:write or swaps:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
application/json- body
A signed vault transaction to relay: one that a deposit or withdraw build on this service returned to the same API key.
xdr*stringThe transaction a vault build on this service returned, signed by caller (base64 envelope XDR).
Created
validation_failed: the body fails validation, or xdr is not a transaction envelope, is a fee bump, or carries no signature. invalid_state_transition: the transaction expired before it was submitted; build a new one.
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 transaction built here for this API key on its network hashes to the signed one: it was changed after the build (anything but the signatures), built for another key or network, or never built here. The same answer for all of them.
Another submit of the same transaction is waiting for the vault protocol. Submit again once it finishes to read its stored answer.
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.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
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/defindex/submit' \ -H 'Content-Type: application/json' \ -d '{ "xdr": "string"}'{ "txHash": "5f0e8a1d3c7b9e2f4a6c8d0b1e3f5a7c9d2b4e6f8a0c1d3e5f7a9b2c4d6e8f0a", "success": true, "result": { "type": "vault_deposit", "sharesMinted": "9950000" }, "ledger": 61234567, "createdAt": "2026-11-01T12:00:00Z", "latestLedger": 61234570, "latestLedgerCloseTime": "2026-11-01T12:00:15Z", "feeBump": false, "feeCharged": "104210"}