Liquidity Pools
Deposit into and withdraw from Stellar AMM pools, and track your positions.
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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
Idempotency-Key?stringOptional 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- 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*stringAccount funding (and signing) the deposit: the tx source.
assetACode?stringFirst asset of the pair. Native if omitted.
assetAIssuer?stringIssuer account for a non-native first asset.
assetBCode?stringSecond asset of the pair. Native if omitted.
assetBIssuer?stringIssuer account for a non-native second asset.
maxAmountA*stringMaximum amount of the first asset to deposit (decimal, ≤ 7 places).
maxAmountB?stringMaximum 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?numberSlippage 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?stringOptional MEMO_ID (numeric uint64) echoed on-chain for reconciliation.
idempotencyKey?stringOptional 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.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/liquidity-pools/deposit' \ -H 'Content-Type: application/json' \ -d '{ "source": "GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ", "maxAmountA": "1000"}'{ "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"}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
Idempotency-Key?stringOptional 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- 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*stringAccount holding the pool shares (and signing): the tx source.
poolId*stringStellar liquidity pool id (64-char hex).
shares*stringAmount of pool shares to burn (decimal, ≤ 7 places).
slippageBps?numberSlippage tolerance in basis points (50 = 0.5%) used to derive the on-chain minimum received per reserve. Defaults to the service setting.
memo?stringOptional MEMO_ID (numeric uint64) echoed on-chain for reconciliation.
idempotencyKey?stringOptional 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.
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"}'{ "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"}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
account*stringAccount 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.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/liquidity-pools/positions?account=GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZ'{ "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" } ] } ]}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
kind?stringOnly operations of this kind (DEPOSIT or WITHDRAW).
"DEPOSIT""WITHDRAW"status?stringOnly operations in this status.
"PENDING""SUBMITTED""SUCCEEDED""FAILED""EXPIRED"take?numberHow many operations to return per page (1 to 100).
value <= 10020skip?numberHow many matching operations to skip before the page starts (newest first).
0OK
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.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/liquidity-pools/operations'{ "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}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*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.
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/liquidity-pools/operations/string'{ "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"}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringapplication/json- 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*stringThe 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.
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="}'{ "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" }}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
assetACode?stringFilter to pools containing this asset. Pass "XLM"/"native" for lumens.
assetAIssuer?stringIssuer for a non-native first asset.
assetBCode?stringSecond asset of the pair (narrows to the exact pool).
assetBIssuer?stringIssuer for a non-native second asset.
account?stringOnly pools this account participates in.
cursor?stringHorizon paging cursor.
limit?numberHow many pools to return per page (1 to 100). Page on with the cursor the answer returns.
value <= 10020OK
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.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/liquidity-pools'{ "data": [ { "id": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7", "network": "testnet", "feeBp": 30, "totalTrustlines": "123", "totalShares": "4462.7227546", "reserves": [ { "asset": "native", "issuer": null, "amount": "82944.5873463" } ] } ], "cursor": "113725249324879873"}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.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
poolId*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.
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 GET 'https://api.cosmospay.lat/cosmos-api/v1/liquidity-pools/string'{ "id": "dd7b1ab831c273310ddbec6f97870aa83c2fbd78ce22aded37ecbf4f3380fac7", "network": "testnet", "feeBp": 30, "totalTrustlines": "123", "totalShares": "4462.7227546", "reserves": [ { "asset": "native", "issuer": null, "amount": "82944.5873463" } ]}Private Checkout
What the payer's browser reads and calls without a key: one private payment, the network's confidential-token setup, and the confirmation of the two confidential transfers that pay it.
Assets
The asset registry: which (code, issuer) pairs exist per network and who issues them. `verified` is a claim about the issuer’s identity, not about quality.