Distribution And Liquidity
Create downstream clients, provision accounts, and move liquidity.
This workflow turns an admitted enterprise perimeter into an operable downstream topology with client resources, client accounts, payout surfaces, deposit surfaces, and initial internal transfers.
Operational Sequence
1. Create the client
Downstream topology resource. Create the client before provisioning additional accounts, payout destinations, or client-scoped liquidity. The public contract can atomically create the default client account alongside the client.
Request URL
POST https://business-api.youhodler.com/clientsRequest Body
{
"parent": "enterprises/11111111-1111-4111-8111-111111111111",
"external_id": "client-acme-retail-eu",
"display_name": "Acme Retail Europe",
"client_account_display_name": "Primary EUR Treasury",
"metadata": {
"segment": "retail",
"region": "eu"
}
}Response
{
"id": "88888888-8888-4888-8888-888888888888",
"resource": "client",
"status": "active",
"parent": "enterprises/11111111-1111-4111-8111-111111111111",
"external_id": "client-acme-retail-eu",
"display_name": "Acme Retail Europe",
"default_client_account": "client-accounts/99999999-9999-4999-8999-999999999999",
"metadata": {
"segment": "retail",
"region": "eu"
},
"created_at": "2026-04-28T13:12:01.000Z",
"updated_at": "2026-04-28T13:12:01.000Z",
"etag": "W/\"client-1\""
}The response can include the default client account ref. Keep it, because the next steps will usually branch from that account boundary.
2. Create additional client accounts
Financial operating accounts. Use additional client accounts when one client needs separate operating boundaries for currencies, regions, or product lines. These accounts become the execution anchors for balances and operations.
Request URL
POST https://business-api.youhodler.com/client-accountsRequest Body
{
"client": "clients/88888888-8888-4888-8888-888888888888",
"display_name": "USDC Settlement Account",
"metadata": {
"purpose": "settlement",
"asset": "USDC"
}
}Response
{
"id": "aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
"resource": "client_account",
"status": "active",
"client": "clients/88888888-8888-4888-8888-888888888888",
"display_name": "USDC Settlement Account",
"created_at": "2026-04-28T13:14:33.000Z",
"updated_at": "2026-04-28T13:14:33.000Z",
"etag": "W/\"client-account-1\""
}Keep the created client account ids handy. They become the `account_ref` targets for internal transfers, withdrawals, conversions, and ramp sessions.
3. Create payout, withdrawal, and webhook surfaces
Money in and money out setup. Provision reusable surfaces before regular execution begins. This usually includes a withdrawal destination for outbound settlement and at least one webhook endpoint for asynchronous delivery.
Request URL
POST https://business-api.youhodler.com/withdrawal-destinationsRequest Body
{
"rail_class": "crypto",
"idempotency_key": "4b3d6e0c-f4a5-47f4-a5ab-4d568d0a9f10",
"crypto_routing": {
"asset": "USDC",
"network": "ethereum",
"address": "0x5F8d1D0B3D6A7f7A4d0F8fB23e8f420f4bB01234"
}
}Request Body
{
"enterprise_id": "11111111-1111-4111-8111-111111111111",
"url": "https://api.acme.example/webhooks/b2b2x",
"event_types": [
"operation.created",
"operation.updated",
"approval.updated"
],
"secret": "replace-with-shared-secret"
}Response
{
"id": "bbbbbbb2-bbbb-4bbb-8bbb-bbbbbbbbbbb2",
"rail_class": "crypto",
"status": "enabled",
"asset": "USDC",
"label": null,
"created_at": "2026-04-28T13:18:02.000Z",
"updated_at": "2026-04-28T13:18:02.000Z",
"crypto_routing": {
"asset": "USDC",
"network": "ethereum",
"address": "0x5F8d1D0B3D6A7f7A4d0F8fB23e8f420f4bB01234"
},
"fiat_routing": null
}If the integration is event-driven, create the webhook endpoint in the same provisioning window so downstream operations can emit into a live consumer from day one.
4. Distribute liquidity
Internal transfers. Move balances from enterprise-owned master accounts into client accounts only after the client account boundary is ready. This gives downstream operations an execution balance without weakening ownership semantics.
Request URL
POST https://business-api.youhodler.com/internal-transfersRequest Headers
Authorization: Bearer <token>
Idempotency-Key: 2db7da81-dc19-4781-8a8b-3a5cb460d142
Content-Type: application/jsonRequest Body
{
"amount": {
"amount": "250000.00",
"currency": "USDC"
},
"source_ref": "master-accounts/22222222-2222-4222-8222-222222222222",
"target_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1"
}Response
{
"id": "ddddddd4-dddd-4ddd-8ddd-ddddddddddd4",
"family": "internal_transfer",
"status": "processing",
"account_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
"principal_amount": {
"amount": "250000.00",
"currency": "USDC"
},
"fee_summary": null,
"fill_rate": null,
"failure_reason": null,
"approval_ref": null,
"subject_attribution": {
"subject_ref": "enterprises/11111111-1111-4111-8111-111111111111"
},
"family_params": {
"source_ref": "master-accounts/22222222-2222-4222-8222-222222222222",
"target_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1"
},
"created_at": "2026-04-28T13:23:04.000Z",
"updated_at": "2026-04-28T13:23:04.000Z"
}Internal transfers are also the same family you will later use for rebalancing or returning liquidity during settlement and suspension.
5. Confirm balances and delivery readiness
Readiness check. Before operational workloads start, read the client-account balance rows and confirm that the webhook endpoint is enabled. This makes the downstream perimeter observable before live execution begins.
Request URL
GET https://business-api.youhodler.com/client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1/balances?asset=USDCRequest URL
POST https://business-api.youhodler.com/webhook-endpoints/ccccccc3-cccc-4ccc-8ccc-ccccccccccc3/enableResponse
{
"items": [
{
"asset": "USDC",
"available": "250000.00",
"pending_in": "0.00",
"pending_out": "0.00"
}
]
}At this point, the client should have an operating entity, at least one active financial account, a delivery path for events, and a visible execution balance.