Clients And Accounts
This group covers downstream topology and downstream financial operating accounts. Read it in operating order: create the downstream tenant first, provision the execution account second, inspect balances third, and only then move liquidity or inspect transfer state.
Downstream Perimeter And Liquidity
Create client
Downstream topology resource. Create a client before any client-scoped account, balance, or operation work can exist.
Request URL
POST https://business-api.youhodler.com/clientsRequest Body
{
"display_name": "Acme Corp",
"external_id": "ext-client-0042",
"metadata": {
"crm_id": "CRM-001",
"tier": "premium"
},
"scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}Response
{
"created_at": "2026-05-01T10:00:00Z",
"default_client_account": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"display_name": "Acme Corp",
"etag": "W/\"a1b2c3d4\"",
"external_id": "ext-client-0042",
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"metadata": {
"crm_id": "CRM-001",
"tier": "premium"
},
"resource": "client",
"scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"status": "active",
"updated_at": "2026-05-01T10:00:00Z"
}Create client account
Execution boundary. Create an additional client account when one client needs multiple financial operating boundaries.
Request URL
POST https://business-api.youhodler.com/client-accountsRequest Body
{
"display_name": "Operating Account EUR",
"scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}Response
{
"created_at": "2026-05-01T10:00:00Z",
"display_name": "Operating Account",
"etag": "W/\"a1b2c3d4\"",
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"resource": "client_account",
"scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"status": "active",
"updated_at": "2026-05-01T10:00:00Z"
}List client account balances
Balance readiness. Read client-account balances when the integration needs to confirm that liquidity is present before live execution starts.
Request URL
GET https://business-api.youhodler.com/client-accounts/aaa111/balances?asset=USDResponse
{
"items": [
{
"asset": "USDC",
"available": "950.00",
"held": "50.00",
"overdraft_headroom": null,
"overdraft_limit": null,
"overdraft_used": null,
"owner_ref": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"owner_subtype": "client_account",
"total": "1000.00",
"updated_at": "2026-05-01T10:00:00Z"
}
]
}Create internal transfer
Liquidity movement. Create an internal transfer when the enterprise needs to move value from a master account into a client account without changing tenant ownership semantics.
Request URL
POST https://business-api.youhodler.com/internal-transfersRequest Body
{
"amount": {
"currency": "USDC",
"value": "250.00"
},
"source_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"target_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}Response
{
"account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"approval_ref": null,
"created_at": "2026-05-01T10:00:00Z",
"failure_reason": null,
"family": "internal_transfer",
"family_params": {
"source_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"target_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"fee_summary": {
"components": [
{
"amount": {
"currency": "USDC",
"value": "1.00"
},
"kind": "network_fee"
}
],
"total": {
"currency": "USDC",
"value": "1.00"
}
},
"fill_rate": null,
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"principal_amount": {
"currency": "USDC",
"value": "250.00"
},
"settled_at": "2026-05-01T10:00:00Z",
"status": "executed",
"subject_attribution": {
"actor": null,
"approved_by": null,
"authenticated_principal": {
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"enterprise_binding": {
"tenant_type": "enterprise",
"topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"federation": null,
"identity_source": "platform-managed",
"initiated_by": null,
"subject": {
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
},
"updated_at": "2026-05-01T10:00:00Z"
}Get internal transfer
Transfer state read. Read the internal transfer directly when the caller needs the current lifecycle state after submission.
Request URL
GET https://business-api.youhodler.com/internal-transfers/it_456Response
{
"account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"approval_ref": null,
"created_at": "2026-05-01T10:00:00Z",
"failure_reason": null,
"family": "internal_transfer",
"family_params": {
"source_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"target_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"fee_summary": {
"components": [
{
"amount": {
"currency": "USDC",
"value": "1.00"
},
"kind": "network_fee"
}
],
"total": {
"currency": "USDC",
"value": "1.00"
}
},
"fill_rate": null,
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"principal_amount": {
"currency": "USDC",
"value": "250.00"
},
"settled_at": "2026-05-01T10:00:00Z",
"status": "executed",
"subject_attribution": {
"actor": null,
"approved_by": null,
"authenticated_principal": {
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"enterprise_binding": {
"tenant_type": "enterprise",
"topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"federation": null,
"identity_source": "platform-managed",
"initiated_by": null,
"subject": {
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
},
"updated_at": "2026-05-01T10:00:00Z"
}