curl --request GET \
--url https://api.1-funnel.org/v1/businesses/{businessId}/wallet/balance \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.1-funnel.org/v1/businesses/{businessId}/wallet/balance', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.1-funnel.org/v1/businesses/{businessId}/wallet/balance"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)HttpResponse<String> response = Unirest.get("https://api.1-funnel.org/v1/businesses/{businessId}/wallet/balance")
.header("Authorization", "Bearer <token>")
.asString();{
"business_id": "018f3c4e-7b2a-7c3d-8e9f-0123456789ab",
"business_name": "Example Business",
"currency": "NGN",
"current_balance": "15000.00",
"available_balance": "15000.00",
"reserved_balance": "0.00",
"as_of": "2026-10-13T09:00:00.000Z"
}Retrieve wallet balance
Read-only balance for the granted business (ADR-019). Requires an active
application-to-business grant and wallet.balance.read. {businessId} is
a selector, not proof (ADR-016).
reserved_balance is always "0.00" in v1 and must not be interpreted as
evidence of reservation accounting. When the authoritative wallet source is
unavailable, return a Problem Details error — do not fabricate zero balances.
curl --request GET \
--url https://api.1-funnel.org/v1/businesses/{businessId}/wallet/balance \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.1-funnel.org/v1/businesses/{businessId}/wallet/balance', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.1-funnel.org/v1/businesses/{businessId}/wallet/balance"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)HttpResponse<String> response = Unirest.get("https://api.1-funnel.org/v1/businesses/{businessId}/wallet/balance")
.header("Authorization", "Bearer <token>")
.asString();{
"business_id": "018f3c4e-7b2a-7c3d-8e9f-0123456789ab",
"business_name": "Example Business",
"currency": "NGN",
"current_balance": "15000.00",
"available_balance": "15000.00",
"reserved_balance": "0.00",
"as_of": "2026-10-13T09:00:00.000Z"
}Authorizations
OAuth 2.0 Client Credentials for the External Integration API (ADR-015, ADR-023).
Client authentication: HTTP Basic (client_secret_basic).
Access-token audience: 1funnel-external-api.
The tokenUrl below is the production target. Sandbox uses a different
host. OpenAPI cannot bind tokenUrl to the selected servers entry; see
x-1funnel-oauth on the root document and the authentication guide when published.
Coarse OAuth scopes (if any) are token-level vocabulary (ADR-013 IA-06). They
are not the ADR-022 resource permission catalogue. Resource permissions
are enforced after token validation via application-to-business grants
(ADR-016) and are documented per operation with x-required-permissions.
These URLs are architecture targets. They are not claimed to be deployed or generally available.
Headers
Request correlation identifier (STD-API-01 D12). Clients may supply a value
of 1–128 characters matching A-Za-z0-9._-. Missing or invalid values are
replaced by a server-generated identifier. Distinct from W3C traceparent,
resource ids, Idempotency-Key, and webhook event ids.
1 - 128^[A-Za-z0-9._-]+$"req_01HZX3K9EXAMPLE"
Path Parameters
Business resource selector in /v1/businesses/{businessId}/… (ADR-006).
UUIDv7-compatible opaque identifier. {businessId} is not authorization
proof. The resource server must independently verify an active
application-to-business grant, required permission, and ownership (ADR-016,
ADR-022).
UUID with version nibble 7 (UUIDv7). STD-API-01 prefers UUIDv7 for new
platform-generated external resource identifiers. Clients must still treat
the value as opaque. Not every path parameter is guaranteed to be v7 solely
because it is a UUID; use this schema where the contract asserts UUIDv7.
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"018f3c4e-7b2a-7c3d-8e9f-0123456789ab"
Response
Authoritative balance snapshot
Read-only wallet balance (ADR-019 WAL-01–WAL-05). reserved_balance is a v1
compatibility field always "0.00" — not evidence of operational reservation
accounting. Do not fabricate balances when the authoritative source is
unavailable; return 503 / balance_unavailable (or service_unavailable).
UUID with version nibble 7 (UUIDv7). STD-API-01 prefers UUIDv7 for new
platform-generated external resource identifiers. Clients must still treat
the value as opaque. Not every path parameter is guaranteed to be v7 solely
because it is a UUID; use this schema where the contract asserts UUIDv7.
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"018f3c4e-7b2a-7c3d-8e9f-0123456789ab"
1 - 256ISO 4217 alphabetic currency code (STD-API-01 D07).
3^[A-Z]{3}$"NGN"
"USD"
Authoritative wallet balance from the platform source of record.
^-?(?:0|[1-9]\d*)(?:\.\d+)?$"15000.00"
"0.00"
"1.5"
Equals current_balance in v1 (compatibility contract).
^-?(?:0|[1-9]\d*)(?:\.\d+)?$"15000.00"
"0.00"
"1.5"
Always "0.00" in v1. Reservations are not implemented. Must not be
inferred or fabricated as nonzero.
^-?(?:0|[1-9]\d*)(?:\.\d+)?$"0.00"
RFC 3339 UTC timestamp for this balance snapshot.
"2026-10-13T09:00:00.000Z"