API Reference

Liquidity Pools

Deposit into and withdraw from Stellar AMM pools, and track your positions.

POST
/v1/liquidity-pools/deposit

Builds a liquidityPoolDeposit on the key's network for source to sign (preceded by the pool-share trustline when the account has none), stores it as PENDING and emits LIQUIDITY_CREATED. Leave maxAmountB out to match the pool’s current ratio (an empty pool needs both amounts, which set its price); the price bounds bracket the pool price by slippageBps (default 50, cap 500 unless configured). Deposits pay no plan commission; a merchantFee is paid from each asset, and source must trust both assets and afford the amounts plus its reserve (trustline_missing, insufficient_balance). An Idempotency-Key (header or body) makes a retry return the same operation.

Requires the liquidity:write or swaps:write scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <API key>

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

Idempotency-Key?string

Optional idempotency key. A retry with the same key and the same request returns the existing operation (same id and txHash); the same key with a different request is 409 idempotency_conflict. Takes precedence over body.idempotencyKey.

application/json
  1. body

A liquidity pool deposit request. The pair may be given in either order: the service reorders it, and its amounts, into the protocol's canonical order.

source*string

Account funding (and signing) the deposit: the tx source.

assetACode?string

First asset of the pair. Native if omitted.

assetAIssuer?string

Issuer account for a non-native first asset.

assetBCode?string

Second asset of the pair. Native if omitted.

assetBIssuer?string

Issuer account for a non-native second asset.

maxAmountA*string

Maximum amount of the first asset to deposit (decimal, ≤ 7 places).

maxAmountB?string

Maximum amount of the second asset. When the pool already has reserves this is derived from the pool price if omitted; it is required when the pool is new or empty (the deposit sets the price).

slippageBps?number

Slippage tolerance in basis points (50 = 0.5%) used to derive the on-chain min/max price bounds. Defaults to the service setting; capped by it.

memo?string

Optional MEMO_ID (numeric uint64) echoed on-chain for reconciliation.

idempotencyKey?string

Optional idempotency key. Prefer the Idempotency-Key request header; when both are set, the header wins. A retry with the same key and the same request returns the existing operation instead of building another transaction; the same key with a different request is 409 idempotency_conflict.

merchantFee?

Your own fee on this deposit: bps of EACH asset it moves, paid to wallet (a Stellar account that can receive both assets) by one payment per asset in the same transaction, beside the plan commission. fixed is refused here: the operation moves two assets. paidBy: recipient takes it from the amounts (less enters the pool); payer adds it on top (the full amounts enter the pool).

Created

validation_failed: The body, query or headers failed validation

invalid_amount: Not a Stellar amount, or not greater than zero

trustline_missing: An account does not trust the asset, and this request cannot add the trustline for it

insufficient_balance: The source account cannot cover the amount, or the XLM reserve the transaction needs

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.

idempotency_conflict: this Idempotency-Key was already used for a different request, or an identical deposit was already built without a key (retry with an Idempotency-Key, or wait for the prior operation to settle or expire).

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/liquidity-pools/deposit' \  -H 'Content-Type: application/json' \  -d '{  "source": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",  "maxAmountA": "1000"}'
Example Response
{  "id": "clx9z8a1b0000abcd1234efgh",  "kind": "DEPOSIT",  "status": "PENDING",  "network": "testnet",  "source": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",  "poolId": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7",  "assetA": "native",  "assetAIssuer": null,  "assetB": "USDC",  "assetBIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTR6F3DSZL5A3W4G4M4N4A5U4QY3T6",  "amountA": "1000",  "amountB": "100",  "shares": null,  "minPrice": "9.95",  "maxPrice": "10.05",  "slippageBps": 50,  "memo": "4242",  "idempotencyKey": "lp-deposit-2026-08-23-001",  "feeBps": 50,  "feeAmountA": "5",  "feeAmountB": "0.5",  "feeWallet": "GBFEE...WALLET",  "merchantFee": {    "bps": 150,    "fixed": "0.25",    "amount": "1.75",    "asset": "XLM",    "wallet": "GBDHAQXQQ75WVBUZ2IX3O7ME7JOKJUOUPUXRNDCORUJODWQCTVUEQ62R",    "paidBy": "recipient",    "amountB": "0.05",    "assetB": "USDC"  },  "commissionMemo": "Cosmos Liquidity Commission",  "xdr": "AAAAAgAAAABx…(base64 XDR)…AAAAAAAAAAA=",  "uri": "web+stellar:tx?xdr=AAAAAgAAAABx…",  "txHash": "3389e9f0...64hex",  "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",  "expiresAt": "2026-07-04T12:39:56.000Z",  "createdAt": "2026-07-04T12:34:56.000Z",  "updatedAt": "2026-07-04T12:34:56.000Z"}
POST
/v1/liquidity-pools/withdraw

Builds a liquidityPoolWithdraw of shares from poolId on the key's network for source to sign, with minimum amounts of each reserve set from the current reserves less slippageBps, stores it as PENDING and emits LIQUIDITY_CREATED. The plan commission is charged only on the gain over the cost basis of shares deposited through this service, out of the withdrawn reserves; a merchantFee is a share of the minimum amounts. A withdrawal from the same pool that may already be on-chain blocks another one for that account (operation_in_flight); an Idempotency-Key (header or body) makes a retry return the same operation.

Requires the liquidity:write or swaps:write scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <API key>

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

Idempotency-Key?string

Optional idempotency key. A retry with the same key and the same request returns the existing operation (same id and txHash); the same key with a different request is 409 idempotency_conflict. Takes precedence over body.idempotencyKey.

application/json
  1. body

A liquidity pool withdrawal request: burn shares pool shares for the proportional amounts of both reserves, protected by slippage-derived on-chain minimums.

source*string

Account holding the pool shares (and signing): the tx source.

poolId*string

Stellar liquidity pool id (64-char hex).

shares*string

Amount of pool shares to burn (decimal, ≤ 7 places).

slippageBps?number

Slippage tolerance in basis points (50 = 0.5%) used to derive the on-chain minimum received per reserve. Defaults to the service setting.

memo?string

Optional MEMO_ID (numeric uint64) echoed on-chain for reconciliation.

idempotencyKey?string

Optional idempotency key. Prefer the Idempotency-Key request header; when both are set, the header wins. A retry with the same key and the same request returns the existing operation instead of building another transaction; the same key with a different request is 409 idempotency_conflict.

merchantFee?

Your own fee on this withdrawal: bps of EACH asset it moves, paid to wallet (a Stellar account that can receive both assets) by one payment per asset in the same transaction, beside the plan commission. fixed is refused here: the operation moves two assets. The fee comes out of what the withdrawal pays, on its guaranteed minimums, whichever paidBy names: the account is payer and receiver.

Created

validation_failed: The body, query or headers failed validation

invalid_amount: Not a Stellar amount, or not greater than zero

insufficient_balance: The source account cannot cover the amount, or the XLM reserve the transaction needs

trustline_missing: An account does not trust the asset, and this request cannot add the trustline for it

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.

idempotency_conflict: this Idempotency-Key was already used for a different request, or an identical withdrawal was already built without a key. operation_in_flight: a withdrawal from this pool is already in flight for this account; wait for it to settle or expire.

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/liquidity-pools/withdraw' \  -H 'Content-Type: application/json' \  -d '{  "source": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",  "poolId": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7",  "shares": "50"}'
Example Response
{  "id": "clx9z8a1b0000abcd1234efgh",  "kind": "DEPOSIT",  "status": "PENDING",  "network": "testnet",  "source": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",  "poolId": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7",  "assetA": "native",  "assetAIssuer": null,  "assetB": "USDC",  "assetBIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTR6F3DSZL5A3W4G4M4N4A5U4QY3T6",  "amountA": "1000",  "amountB": "100",  "shares": null,  "minPrice": "9.95",  "maxPrice": "10.05",  "slippageBps": 50,  "memo": "4242",  "idempotencyKey": "lp-deposit-2026-08-23-001",  "feeBps": 50,  "feeAmountA": "5",  "feeAmountB": "0.5",  "feeWallet": "GBFEE...WALLET",  "merchantFee": {    "bps": 150,    "fixed": "0.25",    "amount": "1.75",    "asset": "XLM",    "wallet": "GBDHAQXQQ75WVBUZ2IX3O7ME7JOKJUOUPUXRNDCORUJODWQCTVUEQ62R",    "paidBy": "recipient",    "amountB": "0.05",    "assetB": "USDC"  },  "commissionMemo": "Cosmos Liquidity Commission",  "xdr": "AAAAAgAAAABx…(base64 XDR)…AAAAAAAAAAA=",  "uri": "web+stellar:tx?xdr=AAAAAgAAAABx…",  "txHash": "3389e9f0...64hex",  "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",  "expiresAt": "2026-07-04T12:39:56.000Z",  "createdAt": "2026-07-04T12:34:56.000Z",  "updatedAt": "2026-07-04T12:34:56.000Z"}
GET
/v1/liquidity-pools/positions

Reads account's pool-share trustlines from Horizon on the key's network and, per pool, its shares, its share of the pool in basis points, the reserves and what those shares redeem now. Ledger data, not this consumer's rows: any account can be read, and nothing is stored.

Requires the liquidity:read or swaps:read scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <API key>

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

account*string

Account whose pool share trustlines to inspect.

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.

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 GET 'https://api.cosmospay.lat/cosmos-api/v1/liquidity-pools/positions?account=GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ'
Example Response
{  "account": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",  "network": "testnet",  "data": [    {      "poolId": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7",      "shares": "50.25",      "totalShares": "4462.7227546",      "shareOfPoolBps": 112,      "reserves": [        {          "asset": "native",          "issuer": null,          "amount": "82944.5873463"        }      ],      "redeemable": [        {          "asset": "native",          "issuer": null,          "amount": "82944.5873463"        }      ]    }  ]}
GET
/v1/liquidity-pools/operations

The deposits and withdrawals built through this service, newest first, optionally filtered by kind and status. Paginated with take (default 20, max 100) and skip; the answer is { data, total, take, skip }. Only operations on the key's network are listed (a prod key sees mainnet, a dev key testnet).

Requires the liquidity:read or swaps:read scope.

apiKey
headerAuthorizationBearer <API key>

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

kind?string

Only operations of this kind (DEPOSIT or WITHDRAW).

Value in"DEPOSIT""WITHDRAW"
status?string

Only operations in this status.

Value in"PENDING""SUBMITTED""SUCCEEDED""FAILED""EXPIRED"
take?number

How many operations to return per page (1 to 100).

Rangevalue <= 100
Default20
skip?number

How many matching operations to skip before the page starts (newest first).

Default0

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.

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/liquidity-pools/operations'
Example Response
{  "data": [    {      "id": "clx9z8a1b0000abcd1234efgh",      "kind": "DEPOSIT",      "status": "PENDING",      "network": "testnet",      "source": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",      "poolId": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7",      "assetA": "native",      "assetAIssuer": null,      "assetB": "USDC",      "assetBIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTR6F3DSZL5A3W4G4M4N4A5U4QY3T6",      "amountA": "1000",      "amountB": "100",      "shares": null,      "minPrice": "9.95",      "maxPrice": "10.05",      "slippageBps": 50,      "memo": "4242",      "idempotencyKey": "lp-deposit-2026-08-23-001",      "feeBps": 50,      "feeAmountA": "5",      "feeAmountB": "0.5",      "feeWallet": "GBFEE...WALLET",      "merchantFee": {        "bps": 150,        "fixed": "0.25",        "amount": "1.75",        "asset": "XLM",        "wallet": "GBDHAQXQQ75WVBUZ2IX3O7ME7JOKJUOUPUXRNDCORUJODWQCTVUEQ62R",        "paidBy": "recipient",        "amountB": "0.05",        "assetB": "USDC"      },      "xdr": "AAAAAgAAAABx…(base64 XDR)…AAAAAAAAAAA=",      "uri": "web+stellar:tx?xdr=AAAAAgAAAABx…",      "txHash": "3389e9f0...64hex",      "expiresAt": "2026-07-04T12:39:56.000Z",      "createdAt": "2026-07-04T12:34:56.000Z",      "updatedAt": "2026-07-04T12:34:56.000Z"    }  ],  "total": 1,  "take": 20,  "skip": 0}
GET
/v1/liquidity-pools/operations/{id}

One deposit or withdrawal this consumer built: its unsigned XDR, SEP-7 uri and QR, its status, and the commission and merchant fee it carries. Answered from this service's own table, which submit and the settlement observer keep current.

Requires the liquidity:read or swaps:read scope.

apiKey
headerAuthorizationBearer <API key>

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

id*string

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.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/liquidity-pools/operations/string'
Example Response
{  "id": "clx9z8a1b0000abcd1234efgh",  "kind": "DEPOSIT",  "status": "PENDING",  "network": "testnet",  "source": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",  "poolId": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7",  "assetA": "native",  "assetAIssuer": null,  "assetB": "USDC",  "assetBIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTR6F3DSZL5A3W4G4M4N4A5U4QY3T6",  "amountA": "1000",  "amountB": "100",  "shares": null,  "minPrice": "9.95",  "maxPrice": "10.05",  "slippageBps": 50,  "memo": "4242",  "idempotencyKey": "lp-deposit-2026-08-23-001",  "feeBps": 50,  "feeAmountA": "5",  "feeAmountB": "0.5",  "feeWallet": "GBFEE...WALLET",  "merchantFee": {    "bps": 150,    "fixed": "0.25",    "amount": "1.75",    "asset": "XLM",    "wallet": "GBDHAQXQQ75WVBUZ2IX3O7ME7JOKJUOUPUXRNDCORUJODWQCTVUEQ62R",    "paidBy": "recipient",    "amountB": "0.05",    "assetB": "USDC"  },  "commissionMemo": "Cosmos Liquidity Commission",  "xdr": "AAAAAgAAAABx…(base64 XDR)…AAAAAAAAAAA=",  "uri": "web+stellar:tx?xdr=AAAAAgAAAABx…",  "txHash": "3389e9f0...64hex",  "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",  "expiresAt": "2026-07-04T12:39:56.000Z",  "createdAt": "2026-07-04T12:34:56.000Z",  "updatedAt": "2026-07-04T12:34:56.000Z"}
POST
/v1/liquidity-pools/operations/{id}/submit

signedXdr must hash to the operation's stored transaction and carry a signature, checked before anything about the operation is answered. It is broadcast through Horizon and the answer is SUCCEEDED or submitted: false with the result codes (a FAILED operation can be resubmitted up to 3 times while its envelope is valid); an unreachable Horizon is a 503 that leaves it resubmittable. Emits LIQUIDITY_SUBMITTED, then LIQUIDITY_SUCCEEDED or LIQUIDITY_FAILED, and a settled deposit records the cost basis the withdrawal commission is charged against.

Requires the liquidity:write or swaps:write scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <API key>

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

id*string
application/json
  1. body

The signed transaction of a liquidity pool operation, to relay to the network. It must be the transaction the service built (its hash is checked) and carry a signature.

signedXdr*string

The signed transaction envelope (base64 XDR).

OK

validation_failed: signedXdr is not a transaction envelope, is not the envelope built for this operation, or carries no signatures. invalid_state_transition: the operation can no longer be submitted, because it is EXPIRED, its transaction's time bounds have passed, or it was already resubmitted the maximum number of times after a rejection. Build a new deposit or withdrawal.

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.

Rate limited (rate_limited), per consumer and client address, in a bucket separate from the swaps submit route. Honour Retry-After: the window is shorter than the envelope lifetime, so a retry after it still lands in time.

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/liquidity-pools/operations/string/submit' \  -H 'Content-Type: application/json' \  -d '{  "signedXdr": "AAAAAgAAAABx…(signed base64 XDR)…AAAAAAAAAAA="}'
Example Response
{  "submitted": true,  "status": "SUCCEEDED",  "txHash": "3389e9f0...64hex",  "reason": null,  "resultCodes": [    "op_bad_price"  ],  "operation": {    "id": "clx9z8a1b0000abcd1234efgh",    "kind": "DEPOSIT",    "status": "PENDING",    "network": "testnet",    "source": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ",    "poolId": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7",    "assetA": "native",    "assetAIssuer": null,    "assetB": "USDC",    "assetBIssuer": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTR6F3DSZL5A3W4G4M4N4A5U4QY3T6",    "amountA": "1000",    "amountB": "100",    "shares": null,    "minPrice": "9.95",    "maxPrice": "10.05",    "slippageBps": 50,    "memo": "4242",    "idempotencyKey": "lp-deposit-2026-08-23-001",    "feeBps": 50,    "feeAmountA": "5",    "feeAmountB": "0.5",    "feeWallet": "GBFEE...WALLET",    "merchantFee": {      "bps": 150,      "fixed": "0.25",      "amount": "1.75",      "asset": "XLM",      "wallet": "GBDHAQXQQ75WVBUZ2IX3O7ME7JOKJUOUPUXRNDCORUJODWQCTVUEQ62R",      "paidBy": "recipient",      "amountB": "0.05",      "assetB": "USDC"    },    "commissionMemo": "Cosmos Liquidity Commission",    "xdr": "AAAAAgAAAABx…(base64 XDR)…AAAAAAAAAAA=",    "uri": "web+stellar:tx?xdr=AAAAAgAAAABx…",    "txHash": "3389e9f0...64hex",    "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA…",    "expiresAt": "2026-07-04T12:39:56.000Z",    "createdAt": "2026-07-04T12:34:56.000Z",    "updatedAt": "2026-07-04T12:34:56.000Z"  }}
GET
/v1/liquidity-pools

Horizon's pool list on the key's network, in descending order, optionally narrowed to pools holding one or two assets (assetACode/assetAIssuer, assetBCode/assetBIssuer) or to those an account holds shares in. Paged by Horizon cursor, not take/skip: limit per page (default 20, max 100), and the answer's cursor fetches the next page (null when the page is not full). Nothing is stored.

Requires the liquidity:read or swaps:read scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <API key>

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

assetACode?string

Filter to pools containing this asset. Pass "XLM"/"native" for lumens.

assetAIssuer?string

Issuer for a non-native first asset.

assetBCode?string

Second asset of the pair (narrows to the exact pool).

assetBIssuer?string

Issuer for a non-native second asset.

account?string

Only pools this account participates in.

cursor?string

Horizon paging cursor.

limit?number

How many pools to return per page (1 to 100). Page on with the cursor the answer returns.

Rangevalue <= 100
Default20

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.

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 GET 'https://api.cosmospay.lat/cosmos-api/v1/liquidity-pools'
Example Response
{  "data": [    {      "id": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7",      "network": "testnet",      "feeBp": 30,      "totalTrustlines": "123",      "totalShares": "4462.7227546",      "reserves": [        {          "asset": "native",          "issuer": null,          "amount": "82944.5873463"        }      ]    }  ],  "cursor": "113725249324879873"}
GET
/v1/liquidity-pools/{poolId}

One pool read from Horizon on the key's network: its fee, trustline count, total shares and reserves. poolId is the 64-character lowercase hex pool id; any other shape is validation_failed, and a pool that does not exist on that network is a 404.

Requires the liquidity:read or swaps:read scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <API key>

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

poolId*string

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.

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/liquidity-pools/string'
Example Response
{  "id": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7",  "network": "testnet",  "feeBp": 30,  "totalTrustlines": "123",  "totalShares": "4462.7227546",  "reserves": [    {      "asset": "native",      "issuer": null,      "amount": "82944.5873463"    }  ]}