Cosmos Pay

Cosmos Pay Payments API

Payments API for merchants and wallets. It covers: payment intents on Stellar, Solana and Monad (with payment links, customers and a product catalog); swaps…

Finance & banking#cryptocurrency

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Payments API for merchants and wallets. It covers: payment intents on Stellar, Solana and Monad (with payment links, customers and a product catalog); swaps on Stellar (path payments), Solana and Monad, cross-chain swaps across Stellar, Solana, Monad and other networks, and USDT0 transfers from Stellar to EVM networks through a bridge; private payments with a hidden amount on Stellar; Stellar liquidity pools and yield vaults; fiat on/offramp and KYC through a fiat partner; and webhooks that notify your server of payment events. Liquidity pools, yield vaults, USDT0, private payments and the SEP-10 and SEP-30 routes are Stellar only. Paths already include the version (/v1/...). Pick the matching server and security scheme below. Every failure returns the same envelope (ApiErrorBodyEntity), and code is the part to branch on: message is prose and may be reworded. Each operation documents only the statuses it can really return: 429 appears where a budget is declared (the budget itself is published as x-cosmos-rate-limit), 502/503/504 where the route calls a provider (x-cosmos-upstream), and neither 401 nor 403 on the probes that need no credentials (x-cosmos-public). Every operation says who may call it. On a route that takes an API key, the description ends with the scope the key must hold, also published as x-cosmos-scopes (all of) and x-cosmos-scopes-any (one of); a key with the admin role passes every scope check, and x-cosmos-public-key marks the routes the shared public key may call. A route that takes no API key (x-cosmos-public) says in its description how it is called. Authenticate every request with your secret API key in the Authorization: Bearer header.

Endpoints 191

payment-intents

  • POSTCreate a SEP-7 `tx` intent (source known → unsigned XDR + tx URI + QR)/v1/payment-intents/txStellar only: builds the unsigned envelope paying destination from source on the key's network (a prod key builds for mainnet, a dev key for testnet), plus a…
  • POSTCreate a `pay` intent: a payment link and QR on Stellar, Solana or Monad/v1/payment-intents/payAnswers a link any wallet can pay and its QR: SEP-7 web+stellar:pay on Stellar (the default chain), Solana Pay on Solana, EIP-681 on Monad, on the key's…
  • GETList the consumer's payment intents/v1/payment-intentsNewest first, as { data, total, take, skip } with take up to 100 (default 20). Only intents on the key's network (a prod key lists mainnet intents, a dev key…
  • GETList the status-transition history for a payment intent/v1/payment-intents/:id/transitionsThe intent's audit trail as an array, oldest first: every status change with fromStatus, toStatus, the txHash it carried, its reason and the actor that made…
  • GETGet a payment intent by id/v1/payment-intents/:idOne of the consumer’s intents, on any chain, with its QR rebuilt from uri. status moves as the on-chain observer settles or expires the intent, which the…
  • DELETEDelete a payment intent/v1/payment-intents/:idDeletes an intent in any status but SUCCEEDED and emits PAYMENT_INTENT_DELETED. A paid intent is a settled payment and cannot be deleted (400…
  • PATCHUpdate a payment intent (status / txHash / reference / checkoutTheme)/v1/payment-intents/:idSend only what changes; reference and checkoutTheme are accepted in any status. status: SUCCEEDED needs a txHash and goes through the same on-chain check as…
  • POSTValidate a transaction against the intent and settle it/v1/payment-intents/:id/validateLooks txHash up on the intent's chain and checks it pays this intent (success, destination, asset, amount, memo or reference, age); a match settles it…

Protected payments

  • GETList your protected payments/v1/protected-paymentsNewest first, as { data, total, take, skip } with take up to 100 (default 20). Only payments on the key’s network, narrowed by status when given, as this…
  • POSTCreate a protected payment (the buyer pays into a contract until delivery)/v1/protected-paymentsCreates a protected payment in USDC on the key’s network, with the release model and the deadline policy of your choice, and answers checkoutUrl, the page to…
  • GETGet one of your protected payments/v1/protected-payments/:idThe payment as this service last read it from its contract (the sync job reads open contracts every 30 seconds), with its fees and checkoutUrl. Requires the…
  • POSTBuild the merchant’s "shipped" mark, with tracking evidence/v1/protected-payments/:id/shipFor a FUNDED payment: the protected-payments service builds the milestone change to shipped with evidence, which this service checks is exactly that call and…
  • POSTBuild the merchant’s approval of delivery (MERCHANT_RELEASES)/v1/protected-payments/:id/approveOnly where the merchant is the approver (MERCHANT_RELEASES), for a FUNDED or SHIPPED payment. Answers the checked envelope for merchantAddress to sign and…
  • POSTBuild the release of the funds to the merchant/v1/protected-payments/:id/releaseWhere the merchant releases (MERCHANT_RELEASES, BUYER_APPROVES_MERCHANT_RELEASES), for an APPROVED payment. The contract pays the amount less 1.95% to…
  • POSTBuild the merchant’s dispute/v1/protected-payments/:id/disputeFor a FUNDED, SHIPPED or APPROVED payment: answers the dispute for merchantAddress to sign and submit. reason is kept by this service only; Cosmos Pay ops (or…
  • POSTCancel a protected payment nobody funded/v1/protected-payments/:id/cancelOnly CREATED, or AWAITING_FUNDING with an empty contract. Refused while a deposit the buyer was handed can still land (it lapses within 15 minutes). Emits…
  • POSTSubmit a merchant-signed protected payment transaction/v1/protected-payments/submitRelays xdr through the protected-payments service only when it is a signed copy of a transaction built for that payment, for merchantAddress, on the key’s…

Protected payment links

  • GETRead a protected payment as its buyer sees it (no API key)/v1/protected-payment-links/:idFor the hosted checkout: the amount, the merchant, the release model, the deadlines, the status and buyerActions, what the buyer may do now. The id is the…
  • POSTBuild the buyer’s deposit into the protected payment (no API key)/v1/protected-payment-links/:id/fundThe first call deploys the payment’s contract (Cosmos Pay pays for it) and binds buyer, once Horizon shows it holds the amount in USDC; a different buyer…
  • POSTBuild the buyer’s confirmation of delivery (no API key)/v1/protected-payment-links/:id/approveWhere the buyer approves (BUYER_RELEASES, BUYER_APPROVES_MERCHANT_RELEASES), for a FUNDED or SHIPPED payment. Answers the checked envelope for the bound buyer…
  • POSTBuild the buyer’s release of the funds (no API key)/v1/protected-payment-links/:id/releaseOnly under BUYER_RELEASES, for an APPROVED payment: the contract pays the merchant the amount less 1.95%. Answers the checked envelope for the bound buyer to…
  • POSTOpen the buyer’s dispute (no API key)/v1/protected-payment-links/:id/disputeWhere the buyer holds a role in the contract, answers built, the dispute for the buyer to sign and submit. Under MERCHANT_RELEASES the buyer holds none, so…
  • POSTSubmit a buyer-signed protected payment transaction (no API key)/v1/protected-payment-links/:id/submitRelays xdr through the protected-payments service only when it is a signed copy of a transaction this link built for the bound buyer, before it expires.…

swaps

  • POSTQuote a swap on one chain; persists nothing/v1/swaps/quotePrices amount of the source asset on the chain's own venue: the Stellar DEX (a Horizon strict-send path search on the key's network) when chain is omitted or…
  • GETList the consumer's swaps on one chain/v1/swapsStellar swaps when chain is omitted, otherwise those of the chain named, newest first and optionally filtered by status. Paginated with take (default 20, max…
  • POSTCreate a swap: the unsigned transaction to sign/v1/swapsPrices the swap as the quote does, builds the transaction source signs, stores it as PENDING and emits SWAP_CREATED. Stellar: the XDR with a SEP-7 uri and QR,…
  • GETGet a swap by id, on any chain/v1/swaps/:idThe shared public key may call it, so a swap made without an account can follow its own status, but only with the swap’s publicToken in X-Record-Token:…
  • POSTRelay the signed swap transaction to its network (checked against the one built); finalizes status/v1/swaps/:id/submitsignedXdr (Stellar) or signedTransaction (Solana, Monad) must be the transaction built for this swap and carry its source's signature, checked before anything…

cross-chain-swaps

  • GETList the assets the cross-chain route can swap, with an indicative USD price/v1/cross-chain-swaps/assetsOnly what the cross-chain route still trades. A token it tags deprecated is left out, and so is one it lists with no price, because it answers no quote for…
  • POSTQuote a cross-chain swap through the cross-chain route (price, commission, minimum); persists nothing/v1/cross-chain-swaps/quoteA dry cross-chain quote for amount of originAsset on originChain into destinationAsset on destinationChain: the expected and minimum output, the plan…
  • GETList the consumer's cross-chain swaps/v1/cross-chain-swapsAnswered from this service's own table, which the observer keeps current from the cross-chain route: newest first, optionally filtered by status. Paginated…
  • POSTCreate a cross-chain swap: a cross-chain deposit address to pay/v1/cross-chain-swapsAsks the cross-chain route for a live quote with a deposit address for this swap alone, stores it as AWAITING_DEPOSIT and emits CROSS_CHAIN_SWAP_CREATED. The…
  • GETGet a cross-chain swap by id/v1/cross-chain-swaps/:idThe shared public key may call it, so a swap made without an account can follow its own status, but only with the swap’s publicToken in X-Record-Token:…
  • POSTReport the deposit transaction to the cross-chain route so the swap starts without waiting for its indexer/v1/cross-chain-swaps/:id/deposittxHash must have the shape of a transaction id on the origin chain; the cross-chain route then reads that chain itself and credits only what really arrived at…

usdt0

  • GETThe networks USDT0 can be sent to from Stellar, with what arrives there (mainnet only)/v1/usdt0/routesUSDT0 is Tether’s omnichain USDT. From Stellar it travels through bridge contract: Ethereum receives native USDT (Tether’s bridge adapter unlocks it), every…
  • POSTQuote a USDT0 transfer from Stellar; persists nothing/v1/usdt0/quoteSimulates the bridge contract quote_oft and quote_send on Stellar mainnet. The bridge contract carries 6 decimals and the asset has 7, so the 7th is dust that…
  • GETList the consumer's USDT0 transfers (not on the shared public key)/v1/usdt0/transfersAnswers from this service’s own table, as last refreshed; read one transfer to refresh it. Refused to the shared public key, which is every anonymous caller…
  • POSTCreate a USDT0 transfer from Stellar → the unsigned Soroban transaction to sign (XDR + SEP-7 link)/v1/usdt0/transfersBuilds send on the USDT0 bridge contract: it burns the USDT0 on Stellar and the bridge delivers it to recipient, as native USDT on Ethereum and as USDT0…
  • GETGet a USDT0 transfer by id, refreshed from the Stellar ledger and the bridge explorer/v1/usdt0/transfers/:idWhile PENDING or SUBMITTED, a read asks the Stellar ledger (a wallet may have broadcast the transaction itself) and the bridge explorer, at most once every 15…
  • POSTRelay the signed USDT0 transaction to Stellar mainnet/v1/usdt0/transfers/:id/submitThe signed XDR must hash to the transfer’s transaction and carry a signature. Accepted and applied: SUBMITTED, with the bridge’s guid. Applied and failed:…

zk-payments

  • GETThe private payments setup of the API key's network/v1/zk-payments/configWhat a dashboard needs to set a merchant up on the confidential token (register, read the balance, withdraw). enabled is false on a network where private…
  • GETList the consumer's private payments/v1/zk-paymentsNewest first, optionally filtered by status as it reads now (a PENDING payment past expiresAt reads, and filters, as EXPIRED). Paginated with take (default…
  • POSTCreate a private payment (0.18% commission)/v1/zk-paymentsA private payment hides its amount on-chain: it is paid with confidential transfers on Cosmos Pay's confidential token, proven with zero-knowledge proofs…
  • GETGet a private payment by id/v1/zk-payments/:idOne of your private payments: its amounts (amount, netAmount, feeAmount), recipient, payer and the hashes of the transfers that settled it. status reads as it…

zk-checkout

  • GETA network's private payments setup, keyless: token, registries, auditor id, commission, fee account/v1/zk-checkout/config?network=testnetThe same shape as GET /v1/zk-payments/config, built by the same code, for a page with no API key: the merchant's confidential-account page (register, balance,…
  • GETRead a private payment as its payer sees it (no API key)/v1/zk-checkout/:idFor a checkout: the gross amount, the net and the commission, the merchant and the fee account to transfer to, the token and the RPC to prove and submit with,…
  • POSTConfirm a private payment with its confidential transfers, verified on-chain (no API key)/v1/zk-checkout/:id/confirmReads both transactions back through the Soroban RPC and settles the payment only when: both succeeded and each is a single confidential_transfer on the…

liquidity-pools

  • POSTBuild a pool deposit → unsigned XDR + SEP-7 tx URI + QR for the wallet to sign/v1/liquidity-pools/depositBuilds 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…
  • POSTBuild a pool withdrawal (burn shares) → unsigned XDR + SEP-7 tx URI + QR/v1/liquidity-pools/withdrawBuilds 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…
  • GETAn account's pool share positions with redeemable amounts/v1/liquidity-pools/positions?account=GA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVSGZReads 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…
  • GETList the consumer's liquidity pool operations/v1/liquidity-pools/operationsThe deposits and withdrawals built through this service, newest first, optionally filtered by kind and status. Paginated with take (default 20, max 100) and…
  • GETGet a liquidity pool operation by id/v1/liquidity-pools/operations/:idOne 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…
  • POSTRelay the signed transaction to the network (hash-checked); finalizes status/v1/liquidity-pools/operations/:id/submitsignedXdr must hash to the operation's stored transaction and carry a signature, checked before anything about the operation is answered. It is broadcast…
  • GETBrowse on-chain liquidity pools (Horizon proxy)/v1/liquidity-poolsHorizon's pool list on the key's network, in descending order, optionally narrowed to pools holding one or two assets (assetACode/assetAIssuer,…
  • GETGet a liquidity pool by id (Horizon proxy)/v1/liquidity-pools/:poolIdOne 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…

assets

  • GETKnown Stellar assets per network, with issuer identity/v1/assetsThe wallet ships a bundled copy of this list and prefers whichever of the two carries the higher version, so a client that cannot reach this endpoint still…

payment-links

  • GETRead a payment link as its payer sees it (no API key)/v1/payment-links/:idFor a hosted checkout page: amount, asset, network, the address to pay (payTo), the link and its QR, and the live status, so the page can poll until the…
  • POSTBuild the envelope a payer signs for a Stellar link with a merchant fee (no API key)/v1/payment-links/:id/transactionA SEP-7 pay link pays one account, so a Stellar payment link with a merchant fee (payerAccountRequired on the link) asks for its payer: given their account,…
  • POSTReport what the payer did with a wallet from the hosted checkout (no API key)/v1/payment-links/:id/eventsThe hosted checkout tells what the payer did with a wallet while the link is pending: walletOpened (the wallet link, the web wallet, the extension or…
  • GETSolana Pay transaction request, GET: the label and icon a wallet shows (no API key)/v1/payment-links/:id/solana-payA Solana payment link with a merchant fee is a Solana Pay transaction request (solana:<this URL>), because a transfer request names one recipient. A wallet…
  • POSTSolana Pay transaction request, POST: the transaction the payer signs (no API key)/v1/payment-links/:id/solana-payGiven the payer’s account, the unsigned transaction (base64) with the link’s memo, the transfer to the merchant carrying the link’s reference, and the…

public-key

  • GETThe shared public API key for an environment/v1/public-keyPublic: no API key, since a wallet without an account holds none yet. env=dev (the default) returns the testnet key and env=prod the mainnet one; that key…

plugins

  • GETList the plugins this deployment serves, with this key’s installations/v1/pluginsEach plugin with its manifest (capabilities, egress, config settings, queries, commands, events) and installation: this consumer's installation of it, or…
  • GETDescribe a plugin: capabilities, egress, settings, actions/v1/plugins/:slugOne plugin's manifest and this consumer's installation of it (null when not installed). Read it before installing: PUT /v1/plugins/{slug}/installation must…
  • PUTInstall a plugin (or re-consent / reconfigure it), granting its capabilities/v1/plugins/:slug/installationInstalling is consent: grantCapabilities must list exactly the capabilities the plugin declares, no more and no fewer (400 plugin_consent_mismatch). config is…
  • DELETEUninstall a plugin and delete every record it kept for this key/v1/plugins/:slug/installationDeletes this consumer's installation and, with it, everything the plugin stored for the consumer. It works even when the deployment no longer serves the…
  • POSTRun a read-only plugin action/v1/plugins/:slug/queries/:actionRuns one of the plugin's queries with input (JSON, at most 64 KiB) and answers its output; a query cannot write the plugin storage, customers or products. The…
  • POSTRun a plugin action that writes/v1/plugins/:slug/commands/:actionRuns one of the plugin's commands with input (JSON, at most 64 KiB) and answers its output; a command may write its own storage and, as far as the granted…

aliases

  • GETResolve an alias to its addresses/v1/aliases/resolve/:nameAnswers the addresses of the alias on one chain (Stellar unless chain names another), optionally narrowed to one network, primary first, with primaryAddress…
  • GETIs this handle claimable, and if not why not/v1/aliases/availability/:nameChecks the trimmed, lowercased handle and answers available, with a reason when it is not: too_short or too_long (3 to 32 characters), bad_characters (a-z,…
  • GETWhich aliases point at this address/v1/aliases/by-address/:addressThe active aliases holding this address, oldest first, each with its chain, network and whether the address is its primary there, as { data } (not paged).…
  • POSTGet a nonce to sign/v1/aliases/challengesReturns the EXACT message to digest and sign. Single-use and short-lived; the purpose is inside the signed bytes, so a signature collected to add an address…
  • GETList the caller's aliases/v1/aliasesThe aliases this consumer holds, newest first, each with its recovery email, status and every address on every chain and network (primary first). Paged with…
  • POSTClaim an alias with a signature/v1/aliasesTakes the nonce of a CLAIM challenge from POST /v1/aliases/challenges and the signature over its message: the address, chain and network registered are the…
  • POSTPoint the alias at another address/v1/aliases/:name/addressesNeeds two proofs: the caller owns the alias, and the NEW address signs for itself. One alias may hold many addresses across many networks. Requires the…
  • DELETERemove one address from the alias/v1/aliases/:name/addresses/:addressIdDeletes one address of an alias this consumer holds. When it was the primary on its chain and network, the oldest remaining address there becomes primary. The…
  • DELETERelease the alias back to the namespace/v1/aliases/:nameDeletes an alias this consumer holds, with all its addresses, so anyone can claim the name again. An alias held by another consumer is a 404. Requires the…
  • POSTStart email recovery: the token is emailed to the owner/v1/aliases/:name/recoveryAlways { accepted: true }, whether or not the alias exists and the mailbox matched: a handle is public and the mailbox behind it is not. When both match, the…
  • POSTFinish recovery: take ownership with a new address/v1/aliases/:name/recovery/completeNeeds the emailed token AND a signature from the new key. Every previous address is dropped: recovery exists because the old keys are gone, and leaving them…

onramp

  • POSTCreate a payin quote (expires in ~5 min)/v1/onramp/quotesPrices a payin through the fiat partner for one of your wallets (blockchain_wallet_id, a Cosmos Pay wallet id) and records the quote as yours, on the fiat…
  • GETList the consumer's payins/v1/onramp/payinsReads this service's mirror only (no fiat partner call), newest first, limited to your key's fiat partner instance; payins still waiting for the fiat…
  • POSTCreate a payin from a quote; returns funding instructions/v1/onramp/payinsExecutes a quote from POST /v1/onramp/quotes at the fiat partner and returns the payin with the instructions the payer follows to fund it off-platform; the…
  • GETGet a payin (serves the local mirror; refreshes from the fiat partner when stale)/v1/onramp/payins/:idAnswers from the mirror while it was updated in the last 60 seconds; an older row is refreshed from the fiat partner first, and when the fiat partner cannot…
  • POSTBuild an unsigned Stellar trustline tx (XDR) for the customer to sign/v1/onramp/trustlineAsks the fiat partner to build the unsigned Stellar transaction that adds the trustline address needs to hold the onramp's stablecoin, and returns the fiat…
  • GETList a receiver's virtual accounts/v1/onramp/receivers/:receiverId/virtual-accountsReads this service's mirror only (no fiat partner call), newest first. The receiver must be yours on your key's fiat partner instance, or the answer is 404.…
  • POSTCreate a virtual account for a receiver/v1/onramp/receivers/:receiverId/virtual-accountsOpens a virtual account at the fiat partner: a bank account in the receiver's name at banking_partner whose deposits are converted to token and sent to…

p2p-onramp

  • GETRead what can be bought with local money/v1/onramp/p2p/marketThe currencies a buyer can pay with on the key's network (a prod key reads mainnet, a dev key the sandbox), each with its payment methods, buy price (local…
  • GETList the tokens a purchase can deliver on one chain/v1/onramp/p2p/tokens?chainId=42161One chain of the market (chainId, one of its networks), a page at a time: each token with its contract address, symbol, decimals and USD price. The network’s…
  • POSTGet a firm price for a purchase with local money/v1/onramp/p2p/quotesThe P2P marketplace prices the order: the token delivered on chainId with fees and the swap taken, the least it can deliver, the rate and the fees, valid…
  • GETList the purchases opened with local money/v1/onramp/p2p/sessionsThe purchases this key's consumer opened on the key's network, newest first, from this service's records (no call to the marketplace). Paginated with take…
  • POSTOpen a purchase with local money/v1/onramp/p2p/sessionsRecords the order and answers widgetUrl, the hosted purchase that takes it: open it in a browser tab or window, where the buyer signs in, verifies their…
  • GETRead a purchase opened with local money/v1/onramp/p2p/sessions/:idOne purchase of this key's consumer on the key's network, from this service's records, with its widget URL. Another consumer's session, one opened on the…

p2p-offramp

  • GETRead what tokens can be sold for local money/v1/offramp/p2p/marketThe currencies a seller can be paid in on the key's network (a prod key reads mainnet, a dev key the sandbox), each with its payment methods, sell price…
  • GETList the tokens a sale can send on one chain/v1/offramp/p2p/tokens?chainId=42161One chain of the market (chainId, one of its networks), a page at a time: each token with its contract address, symbol, decimals and USD price. The network’s…
  • POSTGet a firm price for a sale for local money/v1/offramp/p2p/quotesThe P2P marketplace prices the sale of amount of the token sent from address on chainId: the local money paid with fees taken, the least it can pay, the rate…
  • GETList the sales opened for local money/v1/offramp/p2p/sessionsThe sales this key's consumer opened on the key's network, newest first, from this service's records (no call to the marketplace). Paginated with take…
  • POSTOpen a sale for local money/v1/offramp/p2p/sessionsRecords the order and answers widgetUrl, the hosted sale that takes it: open it in a browser tab or window, where the seller signs in, verifies their…
  • GETRead a sale opened for local money/v1/offramp/p2p/sessions/:idOne sale of this key's consumer on the key's network, from this service's records, with its widget URL. Another consumer's session, one opened on the other…

offramp

  • POSTCreate a payout quote (EVM quote carries the approve contract)/v1/offramp/quotesPrices a payout through the fiat partner of token on network to one of your bank accounts (bank_account_id, a Cosmos Pay id) and records the quote as yours,…
  • POSTBuild the unsigned Stellar/Solana payout tx to sign/v1/offramp/payouts/authorizeStep one of a stellar or solana payout (EVM payouts skip it): the fiat partner builds the transaction sender_wallet_address signs for quote_id, returned as…
  • GETList the consumer's payouts/v1/offramp/payoutsReads this service's mirror only (no fiat partner call), newest first, limited to your key's fiat partner instance; payouts still waiting for the fiat…
  • POSTCreate a payout from a quote/v1/offramp/payoutsExecutes a payout quote at the fiat partner: for evm the customer has already sent the quote's approve, for stellar and solana signed_transaction (from the…
  • GETGet a payout (serves the local mirror; refreshes from the fiat partner when stale)/v1/offramp/payouts/:idAnswers from the mirror while it was updated in the last 60 seconds; an older row is refreshed from the fiat partner first, and when the fiat partner cannot…
  • POSTAttach a compliance document to a payout/v1/offramp/payouts/:id/documentsForwards a document backing the payout (an invoice, for example) to the fiat partner and returns the fiat partner's answer as is. Upload the file first with…

kyc

  • GETList the consumer's receivers/v1/kyc/receiversReads the local mirror only, newest first, on the fiat partner instance of the key's network. Paginated with take (default 100, max 100) and skip; answers {…
  • POSTCreate a receiver (start KYC/KYB)/v1/kyc/receiversStores the receiver here and sends nothing to the fiat partner yet: it is created there only by POST /v1/kyc/receivers/{id}/enable, after the review and the…
  • GETGet a receiver (refreshes KYC status from the fiat partner)/v1/kyc/receivers/:idFor a receiver that already exists at the fiat partner, reads it there and updates the local mirror first, so kycStatus is the fiat partner's current one;…
  • DELETEDelete a receiver/v1/kyc/receivers/:idDeletes the receiver at the fiat partner when it was ever created there, then the local row, and records the deletion in the audit log. A receiver that never…
  • PATCHUpdate a receiver (once it is at the fiat partner, identity fields need an elevated key)/v1/kyc/receivers/:idBefore the receiver exists at the fiat partner, the patch is merged into the stored registration, any change bumps dossierVersion, and editing a pending_user…
  • POSTApprove a receiver's KYC review and get its terms-of-service link/v1/kyc/receivers/:id/approveThe review gate before anything reaches the fiat partner: only a key with the admin role may approve (any other key gets 403 kyc_review_required), and only a…
  • POSTRequest a terms-of-service link for an approved receiver/v1/kyc/receivers/:id/tosOnly for a pending_user receiver (approved, terms not yet accepted); any other status is 400 kyc_state_invalid. Requests a fresh hosted link from the fiat…
  • POSTEnable an inactive receiver with an accepted terms-of-service id/v1/kyc/receivers/:id/enableCreates the receiver at the fiat partner: replays the stored registration with the tos_id the customer got by accepting the terms, then replaces the local…
  • PATCHEnable or disable a fiat account (admin-only kill-switch for onramp/offramp)/v1/kyc/receivers/:id/accessSets disabled on the receiver. While disabled, onramp, offramp and adding wallets, bank accounts or virtual accounts for it are refused with 403…
  • POSTUpload a KYC document; returns its file_url/v1/kyc/uploadMultipart: one file part (JPEG, PNG, WebP, HEIC/HEIF or PDF, up to 10 MB, its bytes checked against the declared type) and an optional bucket (onboarding by…
  • POSTStart ToS acceptance; returns the hosted URL (first KYC step)/v1/kyc/terms-of-serviceAsks the fiat partner for a hosted terms-of-service page and returns its URL; after acceptance the fiat partner redirects to redirect_url (https, on this…

kyc-accounts

  • GETGet the message to sign for the secure wallet flow/v1/kyc/receivers/:receiverId/wallets/sign-messageFetches from the fiat partner the message the customer signs in their own wallet to prove an EOA wallet is theirs. Sign it, then register the wallet with POST…
  • GETList a receiver's wallets/v1/kyc/receivers/:receiverId/walletsReads the local mirror, newest first; the fiat partner is not called. Paginated with take (default 100, max 100) and skip; answers { data, total, take, skip…
  • POSTRegister a blockchain wallet for a receiver/v1/kyc/receivers/:receiverId/walletsRegisters the wallet at the fiat partner under the receiver and mirrors it locally. Send address (account abstraction or the non-secure flow), or the…
  • DELETEDelete a wallet/v1/kyc/receivers/:receiverId/wallets/:idDeletes the wallet at the fiat partner, then its local row. A wallet id this receiver does not have answers deleted: true without calling the fiat partner, so…
  • GETList a receiver's bank accounts/v1/kyc/receivers/:receiverId/bank-accountsReads the local mirror, newest first; the fiat partner is not called, and account numbers are never returned. Paginated with take (default 100, max 100) and…
  • POSTAdd a fiat bank account for a receiver/v1/kyc/receivers/:receiverId/bank-accountsCreates the account at the fiat partner under the receiver and mirrors it; offramp payouts settle to it. type names the rail, and only that rail's fields are…
  • DELETEDelete a bank account/v1/kyc/receivers/:receiverId/bank-accounts/:idDeletes the account at the fiat partner, then its local row. An id this receiver does not have answers deleted: true without calling the fiat partner, so…
  • GETList available bank rails/v1/kyc/railsRelays the fiat partner's catalog of bank rails on the instance of the key's network (production for a mainnet key, development otherwise). Nothing is stored;…
  • GETGet the field schema required by a rail/v1/kyc/bank-details?rail=achRelays the fiat partner's field schema for the rail query parameter (required: 400 validation_failed without it), the fields POST…

Yield vaults

  • GETDiscover yield vaults/v1/defindex/vaultsThe 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…
  • GETRead a yield vault/v1/defindex/vaults/:vaultOne 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…
  • GETRead an account balance in a yield vault/v1/defindex/vaults/:vault/balance?account=stringaccount'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…
  • POSTBuild an unsigned vault deposit/v1/defindex/vaults/:vault/depositThe 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…
  • POSTBuild an unsigned the vault protocol share withdrawal/v1/defindex/vaults/:vault/withdrawThe 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;…
  • POSTSubmit a signed vault transaction/v1/defindex/submitRelays 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…

wallet-auth

  • GETWhich sign-in doors this deployment has/v1/wallet/auth/providersRender buttons from this rather than from a compiled-in list. A deployment with no Google credentials should not show a Google button that dies at the consent…
  • POSTOpen a provider sign-in/v1/wallet/auth/oauth/authorizeReturns the URL to open in a browser. Keep the PKCE verifier on the device: the state travels through the browser and buys only polling, while the verifier is…
  • GETWhere the provider returns the browser after consent/v1/wallet/auth/oauth/callback/:providerNot called by your code: the person’s browser lands here. Public by necessity: a navigation carries no API key and no gateway consumer. It renders a page (or,…
  • GETPoll a sign-in/v1/wallet/auth/oauth/session/:stateAnswers on the state alone, and never returns the identity at any status. Poll until it leaves pending, then redeem with the verifier. Requires the…
  • POSTRedeem a handshake with the PKCE verifier/v1/wallet/auth/oauth/claimA NEW email ends here, with a session token. An email that ALREADY has an account gets verify_email instead and a code in its inbox: a provider proves who…
  • POSTSend a sign-in code to a mailbox/v1/wallet/auth/email/startEmails a six-digit code to email, valid 15 minutes (expiresInSeconds), and answers a claimToken naming that code; send both to POST…
  • POSTAnswer a sign-in code/v1/wallet/auth/email/verifyWrong codes are counted on the row, not by the client. Five burns it, and a burned code is replaced by asking for another. Requires the payments:write scope.…
  • POSTAttach the proven identity to the account this device signs for/v1/wallet/auth/finishSend the session token as X-Wallet-Session: {sessionToken}. The gateway strips Authorization. The signature covers exactly: Cosmos Pay Wallet sign-in email:…
  • PUTReplace the sealed box stored for an account/v1/wallet/backupWhat changePassword on the device sends. No session: the signature is the credential, and it covers the SHA-256 of the box, so one signature stores exactly…
  • POSTSponsor the reserve of an account's two recovery signers/v1/wallet/recovery/setupSend the session token as X-Wallet-Session: {sessionToken}. The gateway strips Authorization. The signature covers exactly: Cosmos Pay Wallet recovery setup…

recovery

  • GETSEP-1 discovery for this recovery server/.well-known/stellar.tomlWEB_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…
  • GETA challenge for an account/v1/sep10/auth?account=stringPublic: 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…
  • POSTExchange a signed challenge for a token/v1/sep10/authWeighed against the account's CURRENT signers and medium threshold, so a recovered account authenticates with the key that replaced its master.
  • POSTExchange an OIDC ID token for this server's identity token/v1/sep30/identitySEP-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…
  • POSTEmail a code that proves an inbox to this server/v1/sep30/identity/email/startThe same answer whether or not the address recovers anything here; a code is only sent to one that does.
  • POSTAnswer an emailed code/v1/sep30/identity/email/verifyPublic: 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…
  • GETAccounts this caller may recover (paged by `after`)/v1/sep30/accountsA 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…
  • GETDescribe an account/v1/sep30/accounts/:addressThe 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…
  • PUTReplace who may recover an account (SEP-10 token of that account)/v1/sep30/accounts/:addressReplaces 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…
  • POSTRegister an account (SEP-10 token of that account)/v1/sep30/accounts/:addressStores 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:…
  • DELETEForget an account (SEP-10 token of that account)/v1/sep30/accounts/:addressDeletes 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…
  • POSTCo-sign a recovery transaction/v1/sep30/accounts/:address/sign/:signerReturns 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.
  • GETEvery half this server holds for the proven inbox (paged by `after`)/v1/sep30/sharesThis server's identity token for an email. One proof brings back the halves of every wallet backed up under it.
  • GETTake this server's half back (the account's key, or its proven inbox)/v1/sep30/shares/:addressThe 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.
  • PUTFile this server's half of a backup's recovery key (SEP-10 token of that account)/v1/sep30/shares/:addressReplaces any half filed before: a re-sealed backup has a new key. The email is who may take the half back.
  • DELETEForget this server's half (SEP-10 token of that account)/v1/sep30/shares/:addressDeletes 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…

wallet-easy-recovery

  • POSTOpen a session on the new device/v1/wallet/easy-recovery/sessionsSend a fresh X25519 public key; keep its private half on the device. Show a QR with the returned id and that key: nothing else, no secret and no server URL.…
  • GETPoll a session/v1/wallet/easy-recovery/sessions/:idBoth devices poll it: the new one waits for offered to ask for the code, the old one for claimed to stop showing it. Answers the status and the expiry only,…
  • POSTOffer the sealed wallet from the old device/v1/wallet/easy-recovery/sessions/:id/offerAfter the person confirmed and unlocked on the old device: seal the wallet to the receiverKey read from the QR (ECIES, on the device), generate a random…
  • POSTClaim the sealed wallet with the code on the old device/v1/wallet/easy-recovery/sessions/:id/claimThe right code answers the sealed wallet, once: the session reads claimed from then on and no longer holds it. A wrong code is a 422 with…

webhooks

  • GETList the consumer's webhook endpoints/v1/webhooksNewest first, as { data, total, take, skip } with take up to 100 (default 100), without signing secrets. destinationBlocked marks an endpoint this service…
  • POSTRegister a webhook endpoint (returns the signing secret, shown once)/v1/webhooksurl must be https, carry no credentials and resolve to a public address (loopback, private, link-local and cloud metadata hosts are 400 validation_failed).…
  • GETGet a webhook endpoint/v1/webhooks/:idThe endpoint without its signing secret, which only the create and rotate-secret routes return. Requires the webhooks:read scope.
  • DELETEDelete a webhook endpoint/v1/webhooks/:idDeletes the endpoint together with its delivery history; nothing more is sent to it. Requires the webhooks:write scope.
  • PATCHUpdate a webhook endpoint (url/description/enabled/eventTypes)/v1/webhooks/:idChanges only the fields sent. A new url is checked as on create, enabled: true checks the stored one again, and either clears destinationBlocked. eventTypes…
  • POSTRotate the signing secret (returns the new secret)/v1/webhooks/:id/rotate-secretReplaces secret at once and returns the new one, shown only here. Every delivery sent from now on is signed with the new secret only: the old one has no grace…
  • POSTSend a test event to verify the endpoint/v1/webhooks/:id/pingPOSTs one signed ping event (not stored as a delivery) to the endpoint, enabled or not, and answers whether it replied 2xx (ok, responseStatus, error). A URL…
  • GETList delivery attempts for an endpoint (audit trail)/v1/webhooks/:id/deliveriesNewest first, as { data, total, take, skip } with take up to 100 (default 20), narrowed by status when given. Each delivery reports its eventType, eventId,…
  • POSTManually re-send a past delivery/v1/webhooks/:id/deliveries/:deliveryId/redeliverRe-sends the stored body with the same event id, signed again with the endpoint's current secret, retrying with backoff inside this request until a 2xx or the…

products

  • GETList the consumer's products/v1/productsNewest first, as { data, total, take, skip } with take up to 100 (default 100). Inactive products (active: false) are included. Requires the products:read…
  • POSTCreate a product/v1/productsA catalog record: name, an optional decimal amount (up to 7 decimals; omit for a customer-set price), assetCode (omitted, XLM or native store native), kind…
  • GETGet a product by id/v1/products/:idOne of the consumer’s products, active or not. Requires the products:read scope.
  • DELETEDelete a product/v1/products/:idDeletes the product for good. To keep its record, set active: false with PATCH instead. Requires the products:write scope.
  • PATCHUpdate a product/v1/products/:idChanges only the fields sent; assetCode is normalized as on create. Set active: false to retire a product and keep its record. Requires the products:write…

customers

  • GETList the consumer's customers (with payment stats)/v1/customersNewest first, as { data, total, take, skip } with take up to 100 (default 100). Each customer carries payments, succeeded and the gross settled total (amounts…
  • POSTCreate a customer/v1/customersA customer holds up to 20 wallets on Stellar, Solana or Monad (the deprecated account counts as one of them), and a wallet named twice counts once. Payments…
  • GETGet a customer by id/v1/customers/:idThe customer with its wallets, oldest first, and account, the deprecated first wallet's address. Payment stats are on the list only. Requires the…
  • DELETEDelete a customer/v1/customers/:idDeletes the customer and its wallets. Payment intents are kept; a later settled payment from one of those wallets adds its payer back as an automatic…
  • PATCHUpdate a customer/v1/customers/:idChanges only the fields sent (name, alias, note, email, reference). The deprecated account edits the first wallet only: an address replaces or adds it, null…
  • POSTAdd a wallet to a customer/v1/customers/:id/walletsA customer holds any number of wallets (up to 20), on Stellar, Solana or Monad; payments paid from any of them count toward it. A wallet the customer already…
  • DELETERemove a wallet from a customer/v1/customers/:id/wallets/:walletIdPayments from that address stop counting toward this customer, and a later settled payment from it adds it as a new automatic customer. A walletId that is not…

analytics

  • GETOverview metrics: totals, settled volume, webhook health, 30-day series/v1/summaryThe settled volume per asset, and every asset valued in USD at the current market reference price (volumeUsd, indicative). Without those prices the USD fields…
  • GETActivity per day, week, month or year, with the window before/v1/summary/seriesPayments, swaps, liquidity operations, webhook deliveries and private payments, each grouped into the buckets of period (UTC, weeks from Monday, a quiet…
  • GETSettled (and pending) amount per asset/v1/balancesPer chain and asset, what this consumer's payment intents settled (amount, with their count) and what is still PENDING or SUBMITTED (pending), on the API…
  • GETRecent API requests reaching the service (with details)/v1/logsThis consumer's requests, newest first, with method, path, status code, duration, client IP and user agent; the dashboard’s own console calls are left out.…
  • GETRecent webhook deliveries across all endpoints (with details)/v1/logs/webhooksDeliveries to every webhook endpoint of this consumer, newest first: the endpoint and its url, eventType, eventId, attempts, the last responseStatus and…

activity

  • GETRecent client events for this consumer, newest first/v1/activity/eventslevel is a floor, not an exact match: level=warn returns warnings and errors. Requires the activity:read scope.
  • POSTReport a batch of client events (errors, metrics, transactions)/v1/activity/eventsAccepted, not created: the batch is written under the consumer the gateway authenticated, and nothing in the body can change that attribution. Over-long…
  • GETCounts, top event types, top errors and a daily series/v1/activity/summaryRolls up the client events this consumer reported over the last days days (default 7, at most 90), optionally for one source: the total, distinct sessions and…

health

  • GETLiveness probe/v1/health/livenessAnswers { "status": "ok" } while the process is up, without checking any dependency, the database included. Public: no API key, for the orchestrator to probe…
  • GETReadiness probe (checks the database)/v1/health/readinessPings Postgres: 200 with the indicator report when it answers, 503 provider_unavailable when it does not, with a body that names no host or cause (those are…

API details

Base URL
https://api.cosmospay.lat/cosmos-api
Authentication
A bearer token in the Authorization header
A bearer token in the Authorization header
Operations
191 operations on 155 pathsPOST 85GET 83DELETE 13PATCH 6PUT 4
Main resources
recovery 16aliases 11kyc 11wallet-auth 10Protected payments 9kyc-accounts 9webhooks 9liquidity-pools 8payment-intents 8customers 7
Response formats
application/json text/html text/plain
Description format
OpenAPI 3.0.0, API version 1.0

How to test the Cosmos Pay Payments API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Cosmos Pay Payments API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Create a SEP-7 `tx` intent (source known → unsigned XDR + tx URI + QR)” (POST /v1/payment-intents/tx), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Cosmos Pay Payments API?

Payments API for merchants and wallets. It covers: payment intents on Stellar, Solana and Monad (with payment links, customers and a product catalog); swaps… It is listed under Finance & banking and has 191 endpoints.

Who publishes the Cosmos Pay Payments API?

It is listed from Cosmos Pay's public API description (an OpenAPI document), not published by Cosmos Pay on Swastik Codes. Anyone who controls cosmospay.lat can claim the profile by adding a DNS TXT record.

What is the base URL of the Cosmos Pay Payments API?

Requests go to https://api.cosmospay.lat/cosmos-api. Endpoint paths are added to this base URL.

How do I authenticate with the Cosmos Pay Payments API?

It accepts 2 methods: A bearer token in the Authorization header; A bearer token in the Authorization header.

How many endpoints does the Cosmos Pay Payments API have?

191 operations on 155 paths (85 POST, 83 GET, 13 DELETE, 6 PATCH, 4 PUT). The largest groups are recovery, aliases, kyc, wallet-auth.

Is forking the Cosmos Pay Payments API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.