API Reference

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.

GET
/v1/defindex/vaults

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.

apiKey
headerAuthorizationBearer <API key>

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

200

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.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/defindex/vaults'
Example Response
Empty
GET
/v1/defindex/vaults/{vault}

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.

apiKey
headerAuthorizationBearer <API key>

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

vault*string

The vault's contract address (C...).

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_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.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/defindex/vaults/string'
Example Response
Empty
GET
/v1/defindex/vaults/{vault}/balance

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.

apiKey
headerAuthorizationBearer <API key>

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

vault*string

The vault's contract address (C...).

account*string

The Stellar account (G...) whose shares and their underlying value are read.

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_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.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/defindex/vaults/string/balance?account=string'
Example Response
Empty
POST
/v1/defindex/vaults/{vault}/deposit

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.

apiKey
headerAuthorizationBearer <API key>

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

vault*string

The vault's contract address (C...).

application/json
  1. 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*string

The Stellar account (G...) that deposits: the source of the built transaction, and the account that signs it.

invest?boolean

Forwarded to the vault protocol as the invest argument of the vault's deposit call.

Defaulttrue
slippageBps?number

Slippage tolerance in basis points (100 = 1%): how far below amounts the deposit's minimum amounts may be.

Range0 <= value <= 10000
Default100

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.

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.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/defindex/vaults/string/deposit' \  -H 'Content-Type: application/json' \  -d '{  "amounts": [    "10000000"  ],  "caller": "string"}'
Example Response
{  "xdr": "AAAAAgAAAAB…",  "functionName": "deposit",  "params": [    null  ],  "simulationResponse": {}}
POST
/v1/defindex/vaults/{vault}/withdraw

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.

apiKey
headerAuthorizationBearer <API key>

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

vault*string

The vault's contract address (C...).

application/json
  1. 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*string

Vault shares to burn: a non-negative integer string no larger than 9007199254740991.

caller*string

The Stellar account (G...) whose shares are burned: the source of the built transaction, and the account that signs it.

slippageBps?number

Slippage tolerance in basis points (100 = 1%), passed to the vault protocol for the withdrawal's minimum outputs.

Range0 <= value <= 10000
Default100

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.

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.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/defindex/vaults/string/withdraw' \  -H 'Content-Type: application/json' \  -d '{  "shares": "1000000",  "caller": "string"}'
Example Response
{  "xdr": "AAAAAgAAAAB…",  "functionName": "deposit",  "params": [    null  ],  "simulationResponse": {}}
POST
/v1/defindex/submit

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.

apiKey
headerAuthorizationBearer <API key>

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

application/json
  1. body

A signed vault transaction to relay: one that a deposit or withdraw build on this service returned to the same API key.

xdr*string

The 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.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/defindex/submit' \  -H 'Content-Type: application/json' \  -d '{  "xdr": "string"}'
Example Response
{  "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"}