Returns balances for every derived address of the customer wallet — native coin plus
supported stablecoins (USDT/USDC where applicable).
Served from Rach’s database, not a live chain read. The deposit monitor keeps the
stored figure in step with the chain, raising it on deposits and lowering it on spends,
so this endpoint costs nothing and can be polled as often as your UI needs.
Query
Behaviour
(none)
Stored balances, returned immediately.
?refresh=true
Returns stored balances immediately and schedules the monitor to re-read these addresses on its next cycle (typically ≤30s). Responds with refresh_requested: true and refresh_eta_seconds; poll again after that interval. Concurrent refresh requests collapse into one chain read.
?live=true
Reads the chain directly, throttled per address. Needed only for the confirmed-vs-unconfirmed split on BTC/LTC/BCH, or when auditing for drift.
Each address object carries source (database or chain) and an array of per-currency
balances; every supported currency for the network is present, including zeros. Each
balance carries as_of — when that figure was last read from the chain.
spendable is what can actually be sent right now:
XRP: excludes the locked ~1 XRP base reserve.
BTC / LTC / BCH: with ?live=true, confirmed counts confirmed UTXOs only;
balance may include unconfirmed (0-conf) funds.
All other networks:spendable equals balance.
GET
/
api
/
v1
/
wallet
/
{customerID}
/
balances
Balances for a customer wallet
curl --request GET \
--url https://api.rach.finance/api/v1/wallet/{customerID}/balances \
--header 'X-API-Key: <api-key>'
Business API key for server-to-server integrations.
Key prefix determines the environment — no separate flag needed:
test_sk_* = sandbox/testnet, live_sk_* = production/mainnet.
Read the chain directly instead of the stored figure. Throttled per address; use only when you need the confirmed/unconfirmed split or are auditing for drift.
Roughly how long until a requested refresh is reflected. Poll again after this interval.
Example:
30
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Rach","description":"Developer documentation for Rach — crypto payment gateway, WaaS, CaaS stablecoin wallets, swaps, 24/7 monitoring and webhooks.","colors":{"primary":"#8B5CF6","light":"#A78BFA","dark":"#7C3AED"},"logo":{"light":"https://mintcdn.com/rach-finance/JqM0ln4O1zcrC0GI/logo/rach.png?fit=max\u0026auto=format\u0026n=JqM0ln4O1zcrC0GI\u0026q=85\u0026s=a23db7dff16b5f42358dfbf063db7350","dark":"https://mintcdn.com/rach-finance/JqM0ln4O1zcrC0GI/logo/rach-white.png?fit=max\u0026auto=format\u0026n=JqM0ln4O1zcrC0GI\u0026q=85\u0026s=2f65b17ea450ed92913b13573f56f0a5","href":"https://rach.finance"},"favicon":"https://mintcdn.com/rach-finance/JqM0ln4O1zcrC0GI/favicon.png?fit=max\u0026auto=format\u0026n=JqM0ln4O1zcrC0GI\u0026q=85\u0026s=2c7e887a54008974865567f4609381b1","appearance":{"default":"dark"},"navbar":{"links":[{"href":"mailto:support@rach.finance","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://payments.rach.finance"}},"footer":{"socials":{"website":"https://rach.finance","x":"https://x.com/userachhq","instagram":"https://instagram.com/userachhq","youtube":"https://youtube.com/@userachhq","threads":"https://threads.net/@userachhq","facebook":"https://facebook.com/userachhq"}},"integrations":{"gtm":{"tagId":"GTM-XXXXXXX"}},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"rach-finance","hasAudioNarration":false,"actualSubdomain":"rach-finance","customDomains":["docs.rach.finance"],"gitSource":{"type":"gitlab","owner":"tech-team6074316","repo":"rach-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"projectId":77262143,"mountPath":"","label":""},"chroma":{"latestBuiltDeploymentHistoryId":"6ac2034af0d19df76a65ec3c","collectionId":"72553760-02a9-496f-960f-b179dba63a17","liveDeploymentHistoryId":"6ac2034af0d19df76a65ec3c","schemaVersion":"v3"},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6ac2aaaac077714d1a861b0b","clientVersion":"0.0.4045","searchFilterCounts":[{"language":"default","tag":"Payments API","count":62},{"language":"default","tag":"CaaS API","count":37},{"language":"default","tag":"Value-Added Services","count":25},{"language":"default","tag":"Documentation","count":19},{"language":"default","tag":"WaaS (Wallet-as-a-Service)","count":18},{"language":"default","tag":"Get Started","count":10},{"language":"default","tag":"B2B - Escrow","count":10},{"language":"default","tag":"B2B - Users","count":9},{"language":"default","tag":"Core Products","count":7},{"language":"default","tag":"Overview","count":6}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet","slug":"/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet","pageMetadata":{"title":"Balances for a customer wallet","description":"Returns balances for every derived address of the customer wallet — native coin plus\nsupported stablecoins (USDT/USDC where applicable).\n\n**Served from Rach's database, not a live chain read.** The deposit monitor keeps the\nstored figure in step with the chain, raising it on deposits and lowering it on spends,\nso this endpoint costs nothing and can be polled as often as your UI needs.\n\n| Query | Behaviour |\n|-------|-----------|\n| *(none)* | Stored balances, returned immediately. |\n| `?refresh=true` | Returns stored balances immediately **and** schedules the monitor to re-read these addresses on its next cycle (typically ≤30s). Responds with `refresh_requested: true` and `refresh_eta_seconds`; poll again after that interval. Concurrent refresh requests collapse into one chain read. |\n| `?live=true` | Reads the chain directly, throttled per address. Needed only for the confirmed-vs-unconfirmed split on BTC/LTC/BCH, or when auditing for drift. |\n\nEach address object carries `source` (`database` or `chain`) and an array of per-currency\n`balances`; every supported currency for the network is present, including zeros. Each\nbalance carries `as_of` — when that figure was last read from the chain.\n\n`spendable` is what can actually be sent right now:\n- **XRP:** excludes the locked ~1 XRP base reserve.\n- **BTC / LTC / BCH:** with `?live=true`, `confirmed` counts confirmed UTXOs only;\n `balance` may include unconfirmed (0-conf) funds.\n- **All other networks:** `spendable` equals `balance`.\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/{customerID}/balances","href":"/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n em: \"em\",\n li: \"li\",\n p: \"p\",\n strong: \"strong\",\n table: \"table\",\n tbody: \"tbody\",\n td: \"td\",\n th: \"th\",\n thead: \"thead\",\n tr: \"tr\",\n ul: \"ul\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Returns balances for every derived address of the customer wallet — native coin plus\\nsupported stablecoins (USDT/USDC where applicable).\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"Served from Rach’s database, not a live chain read.\"\n }), \" The deposit monitor keeps the\\nstored figure in step with the chain, raising it on deposits and lowering it on spends,\\nso this endpoint costs nothing and can be polled as often as your UI needs.\"]\n }), \"\\n\", _jsxs(_components.table, {\n children: [_jsx(_components.thead, {\n children: _jsxs(_components.tr, {\n children: [_jsx(_components.th, {\n children: \"Query\"\n }), _jsx(_components.th, {\n children: \"Behaviour\"\n })]\n })\n }), _jsxs(_components.tbody, {\n children: [_jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.em, {\n children: \"(none)\"\n })\n }), _jsx(_components.td, {\n children: \"Stored balances, returned immediately.\"\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"?refresh=true\"\n })\n }), _jsxs(_components.td, {\n children: [\"Returns stored balances immediately \", _jsx(_components.strong, {\n children: \"and\"\n }), \" schedules the monitor to re-read these addresses on its next cycle (typically ≤30s). Responds with \", _jsx(_components.code, {\n children: \"refresh_requested: true\"\n }), \" and \", _jsx(_components.code, {\n children: \"refresh_eta_seconds\"\n }), \"; poll again after that interval. Concurrent refresh requests collapse into one chain read.\"]\n })]\n }), _jsxs(_components.tr, {\n children: [_jsx(_components.td, {\n children: _jsx(_components.code, {\n children: \"?live=true\"\n })\n }), _jsx(_components.td, {\n children: \"Reads the chain directly, throttled per address. Needed only for the confirmed-vs-unconfirmed split on BTC/LTC/BCH, or when auditing for drift.\"\n })]\n })]\n })]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Each address object carries \", _jsx(_components.code, {\n children: \"source\"\n }), \" (\", _jsx(_components.code, {\n children: \"database\"\n }), \" or \", _jsx(_components.code, {\n children: \"chain\"\n }), \") and an array of per-currency\\n\", _jsx(_components.code, {\n children: \"balances\"\n }), \"; every supported currency for the network is present, including zeros. Each\\nbalance carries \", _jsx(_components.code, {\n children: \"as_of\"\n }), \" — when that figure was last read from the chain.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.code, {\n children: \"spendable\"\n }), \" is what can actually be sent right now:\"]\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"XRP:\"\n }), \" excludes the locked ~1 XRP base reserve.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"BTC / LTC / BCH:\"\n }), \" with \", _jsx(_components.code, {\n children: \"?live=true\"\n }), \", \", _jsx(_components.code, {\n children: \"confirmed\"\n }), \" counts confirmed UTXOs only;\\n\", _jsx(_components.code, {\n children: \"balance\"\n }), \" may include unconfirmed (0-conf) funds.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.strong, {\n children: \"All other networks:\"\n }), \" \", _jsx(_components.code, {\n children: \"spendable\"\n }), \" equals \", _jsx(_components.code, {\n children: \"balance\"\n }), \".\"]\n }), \"\\n\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Balances for a customer wallet","description":"Returns balances for every derived address of the customer wallet — native coin plus\nsupported stablecoins (USDT/USDC where applicable).\n\n**Served from Rach's database, not a live chain read.** The deposit monitor keeps the\nstored figure in step with the chain, raising it on deposits and lowering it on spends,\nso this endpoint costs nothing and can be polled as often as your UI needs.\n\n| Query | Behaviour |\n|-------|-----------|\n| *(none)* | Stored balances, returned immediately. |\n| `?refresh=true` | Returns stored balances immediately **and** schedules the monitor to re-read these addresses on its next cycle (typically ≤30s). Responds with `refresh_requested: true` and `refresh_eta_seconds`; poll again after that interval. Concurrent refresh requests collapse into one chain read. |\n| `?live=true` | Reads the chain directly, throttled per address. Needed only for the confirmed-vs-unconfirmed split on BTC/LTC/BCH, or when auditing for drift. |\n\nEach address object carries `source` (`database` or `chain`) and an array of per-currency\n`balances`; every supported currency for the network is present, including zeros. Each\nbalance carries `as_of` — when that figure was last read from the chain.\n\n`spendable` is what can actually be sent right now:\n- **XRP:** excludes the locked ~1 XRP base reserve.\n- **BTC / LTC / BCH:** with `?live=true`, `confirmed` counts confirmed UTXOs only;\n `balance` may include unconfirmed (0-conf) funds.\n- **All other networks:** `spendable` equals `balance`.\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/{customerID}/balances","href":"/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":["/_mintlify/custom/rach-finance/390919c57430ba8a/scripts/add-missing-endpoints.js","/_mintlify/custom/rach-finance/1395d9e41ea8d255/scripts/fix-balances-schema.js","/_mintlify/custom/rach-finance/800c53d2efc4d1ca/scripts/fix-stale-descriptions.js","/_mintlify/custom/rach-finance/6403dc646251b28a/scripts/add-vas-endpoints.js"],"openApiReferenceData":{"operation":{"description":"Returns balances for every derived address of the customer wallet — native coin plus\nsupported stablecoins (USDT/USDC where applicable).\n\n**Served from Rach's database, not a live chain read.** The deposit monitor keeps the\nstored figure in step with the chain, raising it on deposits and lowering it on spends,\nso this endpoint costs nothing and can be polled as often as your UI needs.\n\n| Query | Behaviour |\n|-------|-----------|\n| *(none)* | Stored balances, returned immediately. |\n| `?refresh=true` | Returns stored balances immediately **and** schedules the monitor to re-read these addresses on its next cycle (typically ≤30s). Responds with `refresh_requested: true` and `refresh_eta_seconds`; poll again after that interval. Concurrent refresh requests collapse into one chain read. |\n| `?live=true` | Reads the chain directly, throttled per address. Needed only for the confirmed-vs-unconfirmed split on BTC/LTC/BCH, or when auditing for drift. |\n\nEach address object carries `source` (`database` or `chain`) and an array of per-currency\n`balances`; every supported currency for the network is present, including zeros. Each\nbalance carries `as_of` — when that figure was last read from the chain.\n\n`spendable` is what can actually be sent right now:\n- **XRP:** excludes the locked ~1 XRP base reserve.\n- **BTC / LTC / BCH:** with `?live=true`, `confirmed` counts confirmed UTXOs only;\n `balance` may include unconfirmed (0-conf) funds.\n- **All other networks:** `spendable` equals `balance`.\n","parameters":["987be1f6-296a-4552-b788-79df63bf939c","eb015f87-c854-4c79-8b5e-dbdd44b1c158","77361e5e-ad37-44a1-9259-e9a774c9d7f5"],"responses":{"200":"84d4db12-c76d-41c0-a099-20dbff176333","404":"66264b2d-ba62-4730-9c4d-eae57b23cc39"},"security":["81e8a024-4bb1-4e52-a18c-6e5e2dd8bfad"],"summary":"Balances for a customer wallet","tags":["WaaS (Wallet-as-a-Service)"],"method":"get","type":"path","servers":["a2375822-8c47-4267-bb34-3cda9dc0ce5e","b09d631f-9ed5-4d25-9267-b46449e84217"],"path":"/api/v1/wallet/{customerID}/balances","baseUrlOptions":["https://api.rach.finance","http://localhost:8080"],"title":"Balances for a customer wallet","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"987be1f6-296a-4552-b788-79df63bf939c":{"in":"path","name":"customerID","required":true,"schema":{"type":"string","isRequired":true,"uniqueKey":"","typeLabel":"string"}},"eb015f87-c854-4c79-8b5e-dbdd44b1c158":{"in":"query","name":"refresh","required":false,"schema":{"type":"boolean","isRequired":false,"description":"Schedule a monitor re-read of these addresses on its next cycle and return stored balances immediately. Does NOT block on a chain read.","uniqueKey":"","typeLabel":"boolean"},"description":"Schedule a monitor re-read of these addresses on its next cycle and return stored balances immediately. Does NOT block on a chain read."},"77361e5e-ad37-44a1-9259-e9a774c9d7f5":{"in":"query","name":"live","required":false,"schema":{"type":"boolean","isRequired":false,"description":"Read the chain directly instead of the stored figure. Throttled per address; use only when you need the confirmed/unconfirmed split or are auditing for drift.","uniqueKey":"","typeLabel":"boolean"},"description":"Read the chain directly instead of the stored figure. Throttled per address; use only when you need the confirmed/unconfirmed split or are auditing for drift."}},"responses":{"84d4db12-c76d-41c0-a099-20dbff176333":{"description":"Balances per address","content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string","uniqueKey":"customer_id","typeLabel":"string"},"addresses":{"type":"array","items":{"type":"object","properties":{"network":{"type":"string","example":"ETH","uniqueKey":"addresses.items.[INDEX].network","typeLabel":"string"},"address":{"type":"string","description":"EIP-55 checksummed for EVM chains.","uniqueKey":"addresses.items.[INDEX].address","typeLabel":"string"},"index":{"type":"integer","uniqueKey":"addresses.items.[INDEX].index","typeLabel":"integer"},"source":{"type":"string","enum":["database","chain"],"example":"database","description":"Where these figures came from. `database` is the normal path; `chain` appears with `?live=true`, or when this address has never been read before.","uniqueKey":"addresses.items.[INDEX].source","typeLabel":"enum\u003cstring>"},"balances":{"type":"array","description":"One entry per supported currency on the network, including zeros.","items":{"type":"object","properties":{"currency":{"example":"USDT","type":"string","uniqueKey":"addresses.items.[INDEX].balances.items.[INDEX].currency","typeLabel":"string"},"balance":{"type":"string","example":"125.50","description":"Total balance in human units.","uniqueKey":"addresses.items.[INDEX].balances.items.[INDEX].balance","typeLabel":"string"},"spendable":{"type":"string","example":"125.50","description":"Amount spendable right now (XRP minus reserve; UTXO confirmed-only).","uniqueKey":"addresses.items.[INDEX].balances.items.[INDEX].spendable","typeLabel":"string"},"confirmed":{"type":"string","example":"0.04","description":"UTXO chains with `?live=true` only — confirmed-only balance. Omitted otherwise.","uniqueKey":"addresses.items.[INDEX].balances.items.[INDEX].confirmed","typeLabel":"string"},"as_of":{"type":"string","format":"date-time","description":"When this figure was last read from the chain. Omitted on a fresh live read.","uniqueKey":"addresses.items.[INDEX].balances.items.[INDEX].as_of","typeLabel":"string\u003cdate-time>"},"note":{"type":"string","description":"Present when balance and spendable differ (unconfirmed funds, or the XRP reserve).","uniqueKey":"addresses.items.[INDEX].balances.items.[INDEX].note","typeLabel":"string"}},"uniqueKey":"addresses.items.[INDEX].balances.items.[INDEX]","typeLabel":"object"},"uniqueKey":"addresses.items.[INDEX].balances","typeLabel":"object[]"}},"uniqueKey":"addresses.items.[INDEX]","typeLabel":"object"},"uniqueKey":"addresses","typeLabel":"object[]"},"total":{"type":"integer","uniqueKey":"total","typeLabel":"integer"},"note":{"type":"string","description":"Explains the database-backed behaviour and the refresh/live options.","uniqueKey":"note","typeLabel":"string"},"refresh_requested":{"type":"boolean","example":true,"description":"Present only when `?refresh=true` or `?live=true` was passed.","uniqueKey":"refresh_requested","typeLabel":"boolean"},"refresh_eta_seconds":{"type":"integer","example":30,"description":"Roughly how long until a requested refresh is reflected. Poll again after this interval.","uniqueKey":"refresh_eta_seconds","typeLabel":"integer"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"customer_id":"\u003cstring>","addresses":[{"network":"ETH","address":"\u003cstring>","index":123,"source":"database","balances":[{"currency":"USDT","balance":"125.50","spendable":"125.50","confirmed":"0.04","as_of":"2023-11-07T05:31:56Z","note":"\u003cstring>"}]}],"total":123,"note":"\u003cstring>","refresh_requested":true,"refresh_eta_seconds":30}}},"exampleType":"generated"}},"exampleType":"generated"},"66264b2d-ba62-4730-9c4d-eae57b23cc39":{"description":"Wallet not found","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}}},"security":{"81e8a024-4bb1-4e52-a18c-6e5e2dd8bfad":{"ApiKeyAuth":{"description":"Business API key for server-to-server integrations.\nKey prefix determines the environment — no separate flag needed:\n`test_sk_*` = sandbox/testnet, `live_sk_*` = production/mainnet.\n","in":"header","name":"X-API-Key","type":"apiKey","scopes":[]}}},"servers":{"a2375822-8c47-4267-bb34-3cda9dc0ce5e":{"description":"Production","url":"https://api.rach.finance"},"b09d631f-9ed5-4d25-9267-b46449e84217":{"description":"Local development","url":"http://localhost:8080"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"description":"Business API key for server-to-server integrations.\nKey prefix determines the environment — no separate flag needed:\n`test_sk_*` = sandbox/testnet, `live_sk_*` = production/mainnet.\n","in":"header","name":"X-API-Key","type":"apiKey","scopes":[]},"schema":{"title":"X-API-Key","type":"string","description":"Business API key for server-to-server integrations.\nKey prefix determines the environment — no separate flag needed:\n`test_sk_*` = sandbox/testnet, `live_sk_*` = production/mainnet.\n","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"ApiKeyAuth","name":"X-API-Key"}],"title":"ApiKeyAuth"}]},"originalFileLocation":"api-reference/openapi.json"},"subdomain":"rach-finance","siteName":"Rach","title":"Balances for a customer wallet - Rach","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-09-28T11:34:30.687Z","originalFileLocation":"api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"dark\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Returns balances for every derived address of the customer wallet — native coin plus supported stablecoins (USDT/USDC where applicable). Served from Rach\u0026#x27;s database, not a live chain read. The deposit monitor keeps the stored figure in step with the chain, raising it on deposits and lowering it on spends, so this endpoint costs nothing and can be polled as often as your UI needs. | Query | Behaviour | |-------|-----------| | (none) | Stored balances, returned immediately. | | ?refresh=true | Returns stored balances immediately and schedules the monitor to re-read these addresses on its next cycle (typically ≤30s). Responds with refresh_requested: true and refresh_eta_seconds; poll again after that interval. Concurrent refresh requests collapse into one chain read. | | ?live=true | Reads the chain directly, throttled per address. Needed only for the confirmed-vs-unconfirmed split on BTC/LTC/BCH, or when auditing for drift. | Each address object carries source (database or chain) and an array of per-currency balances; every supported currency for the network is present, including zeros. Each balance carries as_of — when that figure was last read from the chain. spendable is what can actually be sent right now: - XRP: excludes the locked ~1 XRP base reserve. - BTC / LTC / BCH: with ?live=true, confirmed counts confirmed UTXOs only; balance may include unconfirmed (0-conf) funds. - All other networks: spendable equals balance.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Rach\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/rach-finance/-7wdBJOkp4YcRXzu/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/rach-finance/-7wdBJOkp4YcRXzu/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/rach-finance/-7wdBJOkp4YcRXzu/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/rach-finance/-7wdBJOkp4YcRXzu/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/rach-finance/-7wdBJOkp4YcRXzu/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/rach-finance/-7wdBJOkp4YcRXzu/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/rach-finance/-7wdBJOkp4YcRXzu/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/rach-finance/-7wdBJOkp4YcRXzu/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/rach-finance/-7wdBJOkp4YcRXzu/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Balances for a customer wallet - Rach\">\u003cmeta data-mint-head property=\"og:description\" content=\"Returns balances for every derived address of the customer wallet — native coin plus supported stablecoins (USDT/USDC where applicable). Served from Rach\u0026#x27;s database, not a live chain read. The deposit monitor keeps the stored figure in step with the chain, raising it on deposits and lowering it on spends, so this endpoint costs nothing and can be polled as often as your UI needs. | Query | Behaviour | |-------|-----------| | (none) | Stored balances, returned immediately. | | ?refresh=true | Returns stored balances immediately and schedules the monitor to re-read these addresses on its next cycle (typically ≤30s). Responds with refresh_requested: true and refresh_eta_seconds; poll again after that interval. Concurrent refresh requests collapse into one chain read. | | ?live=true | Reads the chain directly, throttled per address. Needed only for the confirmed-vs-unconfirmed split on BTC/LTC/BCH, or when auditing for drift. | Each address object carries source (database or chain) and an array of per-currency balances; every supported currency for the network is present, including zeros. Each balance carries as_of — when that figure was last read from the chain. spendable is what can actually be sent right now: - XRP: excludes the locked ~1 XRP base reserve. - BTC / LTC / BCH: with ?live=true, confirmed counts confirmed UTXOs only; balance may include unconfirmed (0-conf) funds. - All other networks: spendable equals balance.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Rach\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://rach-finance.mintlify.app/_mintlify/api/og/v2?division=WaaS+%28Wallet-as-a-Service%29\u0026amp;title=Balances+for+a+customer+wallet\u0026amp;description=Returns+balances+for+every+derived+address+of+the+customer+wallet+%E2%80%94+native+coin+plus%0Asupported+stablecoins+%28USDT%2FUSDC+where+applicable%29.%0A%0A**Served+from+Rach%27s+d\u0026amp;theme=8e6f824155de59b347143c01\u0026amp;signature=3bc1ce771dda112a4b31dd1b7dc914a7bab349835affe126865703ab0f925495\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Balances for a customer wallet - Rach\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Returns balances for every derived address of the customer wallet — native coin plus supported stablecoins (USDT/USDC where applicable). Served from Rach\u0026#x27;s database, not a live chain read. The deposit monitor keeps the stored figure in step with the chain, raising it on deposits and lowering it on spends, so this endpoint costs nothing and can be polled as often as your UI needs. | Query | Behaviour | |-------|-----------| | (none) | Stored balances, returned immediately. | | ?refresh=true | Returns stored balances immediately and schedules the monitor to re-read these addresses on its next cycle (typically ≤30s). Responds with refresh_requested: true and refresh_eta_seconds; poll again after that interval. Concurrent refresh requests collapse into one chain read. | | ?live=true | Reads the chain directly, throttled per address. Needed only for the confirmed-vs-unconfirmed split on BTC/LTC/BCH, or when auditing for drift. | Each address object carries source (database or chain) and an array of per-currency balances; every supported currency for the network is present, including zeros. Each balance carries as_of — when that figure was last read from the chain. spendable is what can actually be sent right now: - XRP: excludes the locked ~1 XRP base reserve. - BTC / LTC / BCH: with ?live=true, confirmed counts confirmed UTXOs only; balance may include unconfirmed (0-conf) funds. - All other networks: spendable equals balance.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://rach-finance.mintlify.app/_mintlify/api/og/v2?division=WaaS+%28Wallet-as-a-Service%29\u0026amp;title=Balances+for+a+customer+wallet\u0026amp;description=Returns+balances+for+every+derived+address+of+the+customer+wallet+%E2%80%94+native+coin+plus%0Asupported+stablecoins+%28USDT%2FUSDC+where+applicable%29.%0A%0A**Served+from+Rach%27s+d\u0026amp;theme=8e6f824155de59b347143c01\u0026amp;signature=3bc1ce771dda112a4b31dd1b7dc914a7bab349835affe126865703ab0f925495\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/rach-finance/-7wdBJOkp4YcRXzu/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Rach\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#8B5CF6\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.rach.finance/#organization\",\"name\":\"Rach\",\"url\":\"https://docs.rach.finance\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/rach-finance/JqM0ln4O1zcrC0GI/logo/rach.png?fit=max\u0026auto=format\u0026n=JqM0ln4O1zcrC0GI\u0026q=85\u0026s=a23db7dff16b5f42358dfbf063db7350\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.rach.finance#website\",\"name\":\"Rach\",\"url\":\"https://docs.rach.finance\",\"publisher\":{\"@id\":\"https://docs.rach.finance/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet#webpage\",\"url\":\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet\",\"name\":\"Balances for a customer wallet\",\"description\":\"Returns balances for every derived address of the customer wallet — native coin plus supported stablecoins (USDT/USDC where applicable). Served from Rach's database, not a live chain read. The deposit monitor keeps the stored figure in step with the chain, raising it on deposits and lowering it on spends, so this endpoint costs nothing and can be polled as often as your UI needs. | Query | Behaviour | |-------|-----------| | (none) | Stored balances, returned immediately. | | ?refresh=true | Returns stored balances immediately and schedules the monitor to re-read these addresses on its next cycle (typically ≤30s). Responds with refresh_requested: true and refresh_eta_seconds; poll again after that interval. Concurrent refresh requests collapse into one chain read. | | ?live=true | Reads the chain directly, throttled per address. Needed only for the confirmed-vs-unconfirmed split on BTC/LTC/BCH, or when auditing for drift. | Each address object carries source (database or chain) and an array of per-currency balances; every supported currency for the network is present, including zeros. Each balance carries as_of — when that figure was last read from the chain. spendable is what can actually be sent right now: - XRP: excludes the locked ~1 XRP base reserve. - BTC / LTC / BCH: with ?live=true, confirmed counts confirmed UTXOs only; balance may include unconfirmed (0-conf) funds. - All other networks: spendable equals balance.\",\"dateModified\":\"2026-09-28T11:34:30.687Z\",\"isPartOf\":{\"@id\":\"https://docs.rach.finance#website\"},\"breadcrumb\":{\"@id\":\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"WaaS (Wallet-as-a-Service)\",\"item\":\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/list-all-derived-addresses-across-all-customers\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Balances for a customer wallet\",\"item\":\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet#apireference\",\"headline\":\"Balances for a customer wallet\",\"name\":\"Balances for a customer wallet\",\"description\":\"Returns balances for every derived address of the customer wallet — native coin plus supported stablecoins (USDT/USDC where applicable). Served from Rach's database, not a live chain read. The deposit monitor keeps the stored figure in step with the chain, raising it on deposits and lowering it on spends, so this endpoint costs nothing and can be polled as often as your UI needs. | Query | Behaviour | |-------|-----------| | (none) | Stored balances, returned immediately. | | ?refresh=true | Returns stored balances immediately and schedules the monitor to re-read these addresses on its next cycle (typically ≤30s). Responds with refresh_requested: true and refresh_eta_seconds; poll again after that interval. Concurrent refresh requests collapse into one chain read. | | ?live=true | Reads the chain directly, throttled per address. Needed only for the confirmed-vs-unconfirmed split on BTC/LTC/BCH, or when auditing for drift. | Each address object carries source (database or chain) and an array of per-currency balances; every supported currency for the network is present, including zeros. Each balance carries as_of — when that figure was last read from the chain. spendable is what can actually be sent right now: - XRP: excludes the locked ~1 XRP base reserve. - BTC / LTC / BCH: with ?live=true, confirmed counts confirmed UTXOs only; balance may include unconfirmed (0-conf) funds. - All other networks: spendable equals balance.\",\"url\":\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet\",\"mainEntityOfPage\":{\"@id\":\"https://docs.rach.finance/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet#webpage\"},\"dateModified\":\"2026-09-28T11:34:30.687Z\",\"publisher\":{\"@id\":\"https://docs.rach.finance/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.rach.finance#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Rach\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Rach","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":""}]},{"tab":"Payments API","groups":[{"group":"Overview","pages":[{"title":"Payments API Reference","href":"/api-reference/introduction"}]},{"group":"Checkout (Crypto Gateway)","pages":[{"title":"List deposit addresses (USDT-USDC only)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/checkout/addresses","href":"/api-reference/checkout-crypto-gateway/list-deposit-addresses-usdt-usdc-only"},{"title":"Create a payment session","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/checkout/create","href":"/api-reference/checkout-crypto-gateway/create-a-payment-session"},{"title":"List payment sessions","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/checkout/list","href":"/api-reference/checkout-crypto-gateway/list-payment-sessions"},{"title":"Get payment gateway statistics","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/checkout/stats","href":"/api-reference/checkout-crypto-gateway/get-payment-gateway-statistics"},{"title":"Verify a payment session status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/checkout/verify/{sessionId}","href":"/api-reference/checkout-crypto-gateway/verify-a-payment-session-status"}]},{"group":"Swap","pages":[{"title":"Execute a swap","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/swap/customer/{customerID}","href":"/api-reference/swap/execute-a-swap"},{"title":"Get swap history for a customer","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/swap/customer/{customerID}/history","href":"/api-reference/swap/get-swap-history-for-a-customer"},{"title":"Get a swap quote","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/swap/quote","href":"/api-reference/swap/get-a-swap-quote"},{"title":"Supported swap tokens per chain","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/swap/tokens","href":"/api-reference/swap/supported-swap-tokens-per-chain"}]},{"group":"WaaS (Wallet-as-a-Service)","pages":[{"title":"List all derived addresses across all customers","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/addresses","href":"/api-reference/waas-wallet-as-a-service/list-all-derived-addresses-across-all-customers"},{"title":"List all customer wallets","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/customers","href":"/api-reference/waas-wallet-as-a-service/list-all-customer-wallets"},{"title":"Create customer HD wallet","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/wallet/customers","href":"/api-reference/waas-wallet-as-a-service/create-customer-hd-wallet"},{"title":"Get WaaS fee earnings summary","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/earnings","href":"/api-reference/waas-wallet-as-a-service/get-waas-fee-earnings-summary"},{"title":"List addresses for a customer","description":"Lists every derived address for the customer with its stored balances.\n\n> **Changed:** `?refresh=true` previously read the chain inline for every address (several\n> RPC calls each). It now **schedules** the monitor to re-read those addresses on its next\n> cycle and returns the stored balances immediately. The balances here come from our\n> database either way.\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/{customerID}/addresses","href":"/api-reference/waas-wallet-as-a-service/list-addresses-for-a-customer"},{"title":"Balances for a customer wallet","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/{customerID}/balances","href":"/api-reference/waas-wallet-as-a-service/balances-for-a-customer-wallet"},{"title":"Derive a blockchain address","description":"Derives a blockchain address for the specified network at the given BIP-44 index.\nSet `enable_monitoring: true` to have the payment monitor watch this address\nfor incoming deposits and push webhooks.\n\nRequires an **active** subscription. Returns `402` if the plan has expired.\nDeriving additional addresses for an existing customer wallet does **not** count\nagainst the wallet cap — only creating a new customer wallet does.\n\n**Deposit lifecycle (when `enable_monitoring: true`):**\n\n| Event | When | Notes |\n|-------|------|-------|\n| `wallet.deposit.detected` | deposit first seen on-chain | may carry `hash_pending: true` |\n| `wallet.deposit.hash_resolved` | real on-chain tx hash resolved | **same `deposit_id`**, `tx_hash` now real |\n| `wallet.deposit.confirmed` | block depth / settlement delay met | safe to credit |\n\n**Idempotency — dedup on `deposit_id`, NOT `tx_hash`.** Every deposit webhook carries a stable\n`deposit_id`; record it and ignore repeats. `tx_hash` may initially be a placeholder (`pending_…`)\nwhen the real on-chain hash isn't indexable yet — then `hash_pending` is `true`, and a follow-up\n`wallet.deposit.hash_resolved` (same `deposit_id`) arrives later with the real `tx_hash`. Update\nthe hash on your existing record; **never credit a second time.**\n\n**Addresses** are always EIP-55 checksummed for EVM chains (ETH/BSC/POL), matching the casing\nreturned by `GET /balances` and `list addresses`. **The native BSC coin is `BNB`** (never `BSC`).\n\nThe `confirmations` field behaviour differs by network:\n\n| Network | Confirmation method | `confirmations` value |\n|---------|--------------------|-----------------------|\n| ETH, BSC, POL | Block depth via `eth_getTransactionReceipt` | Real block count (e.g. `12`) |\n| BTC | Block depth via Esplora API | Real block count (e.g. `6`) |\n| TRX, SOL, LTC, BCH, XRP | Time-based settlement delay | Always `0` even when confirmed |\n\n**TRX/SOL/LTC/BCH/XRP always emit `\"confirmations\": 0`** in the webhook payload — even when\n`status` is `\"confirmed\"`. This is expected: these networks use a settlement delay instead of\nblock depth. Do not treat `confirmations: 0` as an error on these networks.\nUse `status === \"confirmed\"` as the authoritative signal, not the `confirmations` count.\n\n**Do not credit customer funds until you receive `wallet.deposit.confirmed`.**\n\n**Webhook payload shape:**\n```json\n{\n \"event\": \"wallet.deposit.detected\",\n \"data\": {\n \"deposit_id\": 4821, // STABLE idempotency key — dedup on THIS, not tx_hash\n \"customer_id\": \"cus_abc123\",\n \"network\": \"TRX\",\n \"address\": \"TV8f...\", // EVM addresses are EIP-55 checksummed\n \"amount\": \"8.152212\",\n \"currency\": \"USDT\", // native BSC coin is \"BNB\"\n \"tx_hash\": \"pending_a1b2c3...\", // may be a placeholder until resolved\n \"hash_pending\": true, // true ⇒ the real hash arrives via hash_resolved\n \"confirmations\": 0,\n \"status\": \"detected\",\n \"detected_at\": \"2026-07-21T04:41:30Z\",\n \"detected_by\": \"custom\",\n \"safe_to_credit\": false\n }\n}\n```\n\nFollow-up once the real on-chain hash is known (**same `deposit_id`** — update, don't re-credit):\n```json\n{\n \"event\": \"wallet.deposit.hash_resolved\",\n \"data\": { \"deposit_id\": 4821, \"tx_hash\": \"9644c5c5...\", \"hash_pending\": false, \"status\": \"detected\" }\n}\n```\n\nNote: on TRX/SOL/LTC/BCH/XRP `confirmations` stays `0` even when `status` is `\"confirmed\"`\n(settlement-delay networks) — use `status`, not the count.\n\n**Reconciling / normalizing your recorded balances:** the authoritative source is the chain.\nTo (re)sync one customer, call `GET /api/v1/wallet/{customerID}/balances` (live, per-currency,\nwith `confirmed`/`spendable`) and set your stored balance to it; for a full sweep of every\ncustomer use `GET /api/v1/wallet/addresses`. This corrects both any past double-count and any\npreviously-missed deposit in a single pass. Dedup historical deposits by `deposit_id`.\n\nVerify webhook authenticity using `HMAC-SHA256(rawRequestBody, whsec_secret)`, hex-encoded —\nthe signature is in the `X-Webhook-Signature` header (we also send `X-Webhook-Event` and `X-Webhook-ID`).\n","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/wallet/{customerID}/derive","href":"/api-reference/waas-wallet-as-a-service/derive-a-blockchain-address"},{"title":"Export private key for an address","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/wallet/{customerID}/export-key","href":"/api-reference/waas-wallet-as-a-service/export-private-key-for-an-address"},{"title":"Retrieve seed phrase","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/{customerID}/seed","href":"/api-reference/waas-wallet-as-a-service/retrieve-seed-phrase"},{"title":"Get transaction history for customer","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/{customerID}/transactions","href":"/api-reference/waas-wallet-as-a-service/get-transaction-history-for-customer"},{"title":"Send crypto from customer wallet","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/wallet/{customerID}/transfer","href":"/api-reference/waas-wallet-as-a-service/send-crypto-from-customer-wallet"},{"title":"Get your WaaS transfer fee configuration","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/fees","href":"/api-reference/waas-wallet-as-a-service/get-your-waas-transfer-fee-configuration"},{"title":"Set your WaaS transfer fee configuration","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/wallet/fees","href":"/api-reference/waas-wallet-as-a-service/set-your-waas-transfer-fee-configuration"},{"title":"Update fee receiving addresses only","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json put /api/v1/wallet/fees/addresses","href":"/api-reference/waas-wallet-as-a-service/update-fee-receiving-addresses-only"},{"title":"Estimate gas for a transfer (EVM chains)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/wallet/estimate-gas","href":"/api-reference/waas-wallet-as-a-service/estimate-gas-for-a-transfer-evm-chains"},{"title":"List configured wallet assets and exact decimals","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/assets","href":"/api-reference/waas-wallet-as-a-service/list-configured-wallet-assets-and-exact-decimals"},{"title":"Review a transfer and its merchant fee without broadcasting","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/wallet/{customerID}/transfer-quote","href":"/api-reference/waas-wallet-as-a-service/review-a-transfer-and-its-merchant-fee-without-broadcasting"},{"title":"Recover an existing transfer request in this workspace","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/wallet/{customerID}/transfers/{key}","href":"/api-reference/waas-wallet-as-a-service/recover-an-existing-transfer-request-in-this-workspace"}]},{"group":"Market Data","pages":[{"title":"List top 250 coins by market cap","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/market/coins","href":"/api-reference/market-data/list-top-250-coins-by-market-cap"},{"title":"Get full detail for one coin","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/market/coins/{symbol}","href":"/api-reference/market-data/get-full-detail-for-one-coin"},{"title":"Market data health check","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/market/health","href":"/api-reference/market-data/market-data-health-check"},{"title":"Batch price lookup","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/market/prices","href":"/api-reference/market-data/batch-price-lookup"},{"title":"Single coin price","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/market/prices/{symbol}","href":"/api-reference/market-data/single-coin-price"},{"title":"Real-time price WebSocket","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /v1/market/ws","href":"/api-reference/market-data/real-time-price-websocket"}]},{"group":"Value-Added Services","pages":[{"title":"Your funding addresses — where to send USDT/USDC to top up","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/vas/funding-addresses","href":"/api-reference/value-added-services/your-funding-addresses-—-where-to-send-usdtusdc-to-top-up"},{"title":"Your spendable balance","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/vas/balance","href":"/api-reference/value-added-services/your-spendable-balance"},{"title":"Ledger statement — every credit, debit and fee","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/vas/statement","href":"/api-reference/value-added-services/ledger-statement-—-every-credit-debit-and-fee"},{"title":"Dashboard — balance, volumes, spend vs earnings, recent orders","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/vas/dashboard","href":"/api-reference/value-added-services/dashboard-—-balance-volumes-spend-vs-earnings-recent-orders"},{"title":"Your markup — what you earn on every order","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/vas/markup","href":"/api-reference/value-added-services/your-markup-—-what-you-earn-on-every-order"},{"title":"Set your markup","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/vas/markup","href":"/api-reference/value-added-services/set-your-markup"},{"title":"List your orders (all products)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/vas/orders","href":"/api-reference/value-added-services/list-your-orders-all-products"},{"title":"Look up one order by your reference (or its id)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/vas/orders/{reference}","href":"/api-reference/value-added-services/look-up-one-order-by-your-reference-or-its-id"},{"title":"Re-check a processing order against the provider now","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/vas/orders/{reference}/refresh","href":"/api-reference/value-added-services/re-check-a-processing-order-against-the-provider-now"},{"title":"Countries supported for airtime","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/airtime/countries","href":"/api-reference/value-added-services/countries-supported-for-airtime"},{"title":"Mobile networks, data plans and bundles in a country","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/airtime/operators","href":"/api-reference/value-added-services/mobile-networks-data-plans-and-bundles-in-a-country"},{"title":"Detect the mobile network for a phone number","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/airtime/detect","href":"/api-reference/value-added-services/detect-the-mobile-network-for-a-phone-number"},{"title":"Operator promotions — bonuses you can advertise","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/airtime/promotions","href":"/api-reference/value-added-services/operator-promotions-—-bonuses-you-can-advertise"},{"title":"Price a top-up before buying — shows your margin","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/airtime/quote","href":"/api-reference/value-added-services/price-a-top-up-before-buying-—-shows-your-margin"},{"title":"Send airtime, data or a bundle to a phone number","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/airtime/topup","href":"/api-reference/value-added-services/send-airtime-data-or-a-bundle-to-a-phone-number"},{"title":"Countries with gift cards available","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/giftcards/countries","href":"/api-reference/value-added-services/countries-with-gift-cards-available"},{"title":"Gift cards available to buy","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/giftcards/products","href":"/api-reference/value-added-services/gift-cards-available-to-buy"},{"title":"One gift card's full detail, for a product page","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/giftcards/products/{id}","href":"/api-reference/value-added-services/one-gift-cards-full-detail-for-a-product-page"},{"title":"How customers redeem each brand's gift cards","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/giftcards/redeem-instructions","href":"/api-reference/value-added-services/how-customers-redeem-each-brands-gift-cards"},{"title":"Price a gift card before buying — shows your margin","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/giftcards/quote","href":"/api-reference/value-added-services/price-a-gift-card-before-buying-—-shows-your-margin"},{"title":"Buy a gift card","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/giftcards/orders","href":"/api-reference/value-added-services/buy-a-gift-card"},{"title":"Biller categories available in a country","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/bills/types","href":"/api-reference/value-added-services/biller-categories-available-in-a-country"},{"title":"Utility billers available to pay","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/bills/billers","href":"/api-reference/value-added-services/utility-billers-available-to-pay"},{"title":"Price a bill payment before paying — shows your margin","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/bills/quote","href":"/api-reference/value-added-services/price-a-bill-payment-before-paying-—-shows-your-margin"},{"title":"Pay a utility bill","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/bills/pay","href":"/api-reference/value-added-services/pay-a-utility-bill"}]},{"group":"Public Checkout","pages":[{"title":"Get payment session details (public)","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/checkout/{uuid}","href":"/api-reference/public-checkout/get-payment-session-details-public"},{"title":"Customer selects crypto network","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json post /api/v1/checkout/{uuid}/select-network","href":"/api-reference/public-checkout/customer-selects-crypto-network"},{"title":"Force-check payment status","deprecated":null,"version":null,"openapi":"/api-reference/openapi.json get /api/v1/checkout/{uuid}/verify-now","href":"/api-reference/public-checkout/force-check-payment-status"}]}]},{"tab":"CaaS API","pages":[{"title":"CaaS API","href":"/api-reference/caas-introduction"}]}]},"basePath":"","title":"Balances for a customer wallet - Rach","buildId":"dpl_36EDyZCDfRuoUD9af5CH4M1bqY2h","deploymentId":"dpl_36EDyZCDfRuoUD9af5CH4M1bqY2h","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-DCDCdBVX.js","utils-ME8dDnLe.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-0e84ACsd.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-wgRBj-ia.js","snippetPresets-C11Sgb-o.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-C0lapOpP.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-ZeRQV8fF.js","shallow-BupWh095.js","getApiPlaygroundDisplay-BnYQO2Ss.js","CodeSnippet-RKKOc8c_.js","CodeSnippets-Drf_m8wS.js","Page-Bevw23-4.js","getPastedJson-u6QiPzNZ.js","icon-Bb-CBSxO.js","MethodPill-F7l5AI7V.js","DuplicateIcon-IiAXkdSg.js","createIcon-FliI8EBc.js","DynamicMarkdown-B62XqCSI.js","SectionHeading-Dj31pT03.js","axios-vUo_bRtp.js","Markdown-BOgQCTwD.js","clsx-BIWXJmsZ.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-DKZWslLH.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-UDqbR6xh.js"]}