KYC wallets and bank accounts
A receiver's blockchain wallets and fiat bank accounts, the bank rails and the fields each rail asks for.
Fetches from BlindPay the message the customer signs in their own wallet to prove an EOA wallet is theirs. Sign it, then register the wallet with POST /v1/kyc/receivers/{receiverId}/wallets and its signature_tx_hash instead of an address. Nothing is stored.
Requires the kyc:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
receiverId*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.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/wallets/sign-message'Reads the local mirror, newest first; BlindPay is not called. Paginated with take (default 100, max 100) and skip; answers { data, total, take, skip }.
Requires the kyc:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
receiverId*stringtake?numberPage size: how many items to return (1 to 100).
1 <= value <= 100100skip?numberHow many items to skip before this page (offset).
0 <= value0OK
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/kyc/receivers/string/wallets'{ "data": [ { "id": "clz9xwallet001", "blindpayId": "bw_000000000000", "name": "Primary wallet", "network": "stellar", "address": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "isAccountAbstraction": false, "createdAt": "2026-06-28T12:00:00.000Z" } ], "total": 1, "take": 100, "skip": 0}Registers the wallet at BlindPay under the receiver and mirrors it locally. Send address (account abstraction or the non-secure flow), or the signature_tx_hash of the message from GET /v1/kyc/receivers/{receiverId}/wallets/sign-message (secure EOA flow). network is one of BlindPay's: Stellar, Solana, Tron, Ethereum, Base, Arbitrum, Polygon or one of their test networks. A disabled receiver is refused with 403 account_disabled.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
receiverId*stringapplication/json- body
A blockchain wallet to register for a receiver: send address, or the signature_tx_hash of the signed sign-message (secure EOA flow).
name*stringA label for the wallet, forwarded to BlindPay.
network*stringBlindPay network the wallet is on (mainnets and their test networks).
"ethereum""base""arbitrum""polygon""stellar""solana""tron""sepolia""base_sepolia""arbitrum_sepolia""polygon_amoy""stellar_testnet""solana_devnet"address?stringWallet address (account-abstraction / non-secure flow).
signature_tx_hash?stringSigned sign-message tx hash (secure EOA flow).
is_account_abstraction?booleanWhether address is an account-abstraction wallet.
Created
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/wallets' \ -H 'Content-Type: application/json' \ -d '{ "name": "Primary wallet", "network": "stellar"}'{ "id": "clz9xwallet001", "blindpayId": "bw_000000000000", "name": "Primary wallet", "network": "stellar", "address": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "isAccountAbstraction": false, "createdAt": "2026-06-28T12:00:00.000Z"}Deletes the wallet at BlindPay, then its local row. A wallet id this receiver does not have answers deleted: true without calling BlindPay, so repeating a delete succeeds.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
receiverId*stringid*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.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/wallets/string'{ "id": "clz9xwallet001", "deleted": true}Reads the local mirror, newest first; BlindPay is not called, and account numbers are never returned. Paginated with take (default 100, max 100) and skip; answers { data, total, take, skip }.
Requires the kyc:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
receiverId*stringtake?numberPage size: how many items to return (1 to 100).
1 <= value <= 100100skip?numberHow many items to skip before this page (offset).
0 <= value0OK
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/kyc/receivers/string/bank-accounts'{ "data": [ { "id": "clz9xbank00001", "blindpayId": "ba_000000000000", "rail": "ach", "name": "Acme payouts (USD)", "country": "US", "createdAt": "2026-06-28T12:00:00.000Z" } ], "total": 1, "take": 100, "skip": 0}Creates the account at BlindPay under the receiver and mirrors it; offramp payouts settle to it. type names the rail, and only that rail's fields are needed (GET /v1/kyc/bank-details?rail= lists them). The response carries identifiers only (rail, name, country), never the account numbers. A disabled receiver is refused with 403 account_disabled.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
receiverId*stringapplication/json- body
A fiat bank account to add to a receiver, where its offramp payouts settle. type names the rail and only that rail's fields are needed (GET /v1/kyc/bank-details?rail= lists them); the body is forwarded to BlindPay.
type*stringThe rail the account settles on; it decides which of the rail-specific fields apply.
"wire""ach""rtp""pix""pix_safe""ted""spei_bitso""transfers_bitso""ach_cop_bitso""international_swift""sepa"name*stringA label for the account, forwarded to BlindPay.
account_class?stringOwnership class of the account (individual or business), used by the US and EUR rails.
"individual""business"account_type?stringChecking or savings account, for the rails that distinguish them.
"checking""saving"beneficiary_name?stringName of the account's beneficiary.
recipient_relationship?stringRelationship to the recipient, as a BlindPay code (for example first_party).
account_number?stringBank account number (ach, wire and rtp rails, United States).
routing_number?stringBank routing number (ach, wire and rtp rails, United States).
business_industry?stringNAICS code; required for business-class US/SWIFT accounts.
phone_number?stringPhone number with its country code; a compliance field the ACH, Wire, RTP and SWIFT rails may require.
tax_id?stringTax id; a compliance field the ACH, Wire, RTP and SWIFT rails may require.
pix_key?stringPIX key of the destination account, such as an email address (pix rail, Brazil).
pix_safe_bank_code?stringBank code of the destination account (pix_safe rail, Brazil).
pix_safe_branch_code?stringBranch code of the destination account (pix_safe rail, Brazil).
pix_safe_cpf_cnpj?stringCPF or CNPJ (Brazilian tax id) of the account holder (pix_safe rail, Brazil).
ted_bank_code?stringBank code of the destination account (ted rail, Brazil).
ted_branch_code?stringBranch code of the destination account (ted rail, Brazil).
ted_cpf_cnpj?stringCPF or CNPJ (Brazilian tax id) of the account holder (ted rail, Brazil).
transfers_account?stringDestination CVU, CBU or alias (transfers_bitso rail, Argentina); say which in transfers_type.
transfers_type?stringCVU | CBU | ALIAS
spei_clabe?stringCLABE of the destination account (spei_bitso rail, Mexico).
spei_institution_code?stringInstitution code of the destination bank (spei_bitso rail, Mexico).
spei_protocol?stringSPEI protocol value, forwarded to BlindPay (spei_bitso rail, Mexico).
ach_cop_beneficiary_first_name?stringBeneficiary first name (ach_cop_bitso rail, Colombia).
ach_cop_beneficiary_last_name?stringBeneficiary last name (ach_cop_bitso rail, Colombia).
ach_cop_document_id?stringNumber of the beneficiary's identity document (ach_cop_bitso rail, Colombia).
ach_cop_document_type?stringType of the beneficiary's identity document (ach_cop_bitso rail, Colombia).
ach_cop_email?stringBeneficiary email address (ach_cop_bitso rail, Colombia).
ach_cop_bank_code?stringCode of the destination bank (ach_cop_bitso rail, Colombia).
ach_cop_bank_account?stringDestination bank account number (ach_cop_bitso rail, Colombia).
swift_account_holder_name?stringName of the account holder (international_swift rail).
swift_account_number_iban?stringAccount number or IBAN of the destination account (international_swift rail).
swift_code_bic?stringSWIFT/BIC code of the destination bank (international_swift rail).
swift_bank_name?stringName of the destination bank (international_swift rail).
swift_bank_address_line_1?stringFirst line of the destination bank's address (international_swift rail).
swift_bank_city?stringCity of the destination bank (international_swift rail).
swift_bank_state_province_region?stringState, province or region of the destination bank (international_swift rail).
swift_bank_country?stringCountry of the destination bank (international_swift rail).
swift_bank_postal_code?stringPostal code of the destination bank (international_swift rail).
swift_beneficiary_address_line_1?stringFirst line of the beneficiary's address (international_swift rail).
swift_beneficiary_city?stringCity of the beneficiary's address (international_swift rail).
swift_beneficiary_state_province_region?stringState, province or region of the beneficiary's address (international_swift rail).
swift_beneficiary_country?stringCountry of the beneficiary's address (international_swift rail).
swift_beneficiary_postal_code?stringPostal code of the beneficiary's address (international_swift rail).
swift_bank_address_line_2?stringSecond line of the destination bank's address (international_swift rail).
swift_beneficiary_address_line_2?stringSecond line of the beneficiary's address (international_swift rail).
swift_payment_code?stringSWIFT payment/purpose code.
swift_intermediary_bank_swift_code_bic?stringSWIFT/BIC code of the intermediary bank, when the transfer goes through one (international_swift rail).
swift_intermediary_bank_account_number_iban?stringAccount number or IBAN at the intermediary bank (international_swift rail).
swift_intermediary_bank_name?stringName of the intermediary bank (international_swift rail).
swift_intermediary_bank_country?stringCountry of the intermediary bank (international_swift rail).
sepa_iban?stringIBAN of the destination account (sepa rail, EUR).
sepa_beneficiary_bic?stringBIC of the beneficiary's bank (sepa rail).
sepa_beneficiary_legal_name?stringLegal name of the beneficiary (sepa rail).
sepa_beneficiary_address_line_1?stringFirst line of the beneficiary's address (sepa rail).
sepa_beneficiary_city?stringCity of the beneficiary's address (sepa rail).
sepa_beneficiary_postal_code?stringPostal code of the beneficiary's address (sepa rail).
sepa_beneficiary_country?stringCountry of the beneficiary's address (sepa rail).
sepa_beneficiary_address_line_2?stringSecond line of the beneficiary's address (sepa rail).
sepa_beneficiary_state_province_region?stringState, province or region of the beneficiary's address (sepa rail).
address_line_1?stringFirst line of the beneficiary's address, for the US, SWIFT and SEPA rails.
address_line_2?stringSecond line of the beneficiary's address, for the US, SWIFT and SEPA rails.
city?stringCity of the beneficiary's address, for the US, SWIFT and SEPA rails.
state_province_region?stringState, province or region of the beneficiary's address, for the US, SWIFT and SEPA rails.
country?stringCountry of the beneficiary's address, for the US, SWIFT and SEPA rails.
postal_code?stringPostal code of the beneficiary's address, for the US, SWIFT and SEPA rails.
Created
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/bank-accounts' \ -H 'Content-Type: application/json' \ -d '{ "type": "ach", "name": "Acme payouts (USD)"}'{ "id": "clz9xbank00001", "blindpayId": "ba_000000000000", "rail": "ach", "name": "Acme payouts (USD)", "country": "US", "createdAt": "2026-06-28T12:00:00.000Z"}Deletes the account at BlindPay, then its local row. An id this receiver does not have answers deleted: true without calling BlindPay, so repeating a delete succeeds.
Requires the kyc:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
receiverId*stringid*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.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/kyc/receivers/string/bank-accounts/string'{ "id": "clz9xbank00001", "deleted": true}Relays BlindPay's catalog of bank rails on the instance of the key's network (production for a mainnet key, development otherwise). Nothing is stored; the body is BlindPay's answer as returned.
Requires the kyc:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
OK
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/kyc/rails'Relays BlindPay's field schema for the rail query parameter (required: 400 validation_failed without it), the fields POST /v1/kyc/receivers/{receiverId}/bank-accounts needs for that rail. Answered as BlindPay returns it, from the instance of the key's network.
Requires the kyc:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
rail*stringThe rail whose fields to list, as a bank account's type names it (GET /v1/kyc/rails lists the rails). Forwarded to BlindPay as given.
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.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/kyc/bank-details?rail=ach'