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.
Response examples come from the API contract. Replace sample identifiers with
the identifiers returned by your own requests; examples show independent resources.
See each linked endpoint for authentication, required headers, and error responses.
Request lines use the production base URL, as the API reference does. In a
sandbox workspace, send the same requests to https://b2b2x-sandbox.youhodler.com/api.
Operational Sequence
1. Create the client
Request URL
POST https://b2b.youhodler.com/api/clientsRequest Body
{
"external_id": "client-acme-retail-eu",
"display_name": "Acme Retail Europe",
"metadata": {
"segment": "retail",
"region": "eu"
},
"scope_ref": "enterprises/11111111-1111-4111-8111-111111111111"
}Created client
{
"created_at": "2026-05-01T10:00:00Z",
"default_client_account": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"display_name": "Acme Corp",
"etag": "2026-05-01T10:00:00Z",
"external_id": "ext-client-0042",
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kyb_stage": null,
"kyb_state": null,
"kyb_state_updated_at": null,
"kyc_stage": null,
"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 the client account in the next step using the returned client id as scope_ref.
2. Create additional client accounts
Request URL
POST https://b2b.youhodler.com/api/client-accountsRequest Body
{
"display_name": "USDC Settlement Account",
"metadata": {
"purpose": "settlement",
"asset": "USDC"
},
"scope_ref": "clients/88888888-8888-4888-8888-888888888888"
}Created client account
{
"created_at": "2026-05-01T10:00:00Z",
"display_name": "Operating Account",
"etag": "2026-05-01T10:00:00Z",
"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"
}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
Request URL
POST https://b2b.youhodler.com/api/withdrawal-destinationsRequest Body
{
"rail_class": "crypto",
"idempotency_key": "4b3d6e0c-f4a5-47f4-a5ab-4d568d0a9f10",
"crypto_routing": {
"asset": "USDC",
"network": "ethereum",
"destination": {
"address": "0x5F8d1D0B3D6A7f7A4d0F8fB23e8f420f4bB01234",
"memo": null
}
},
"scope_ref": "clients/88888888-8888-4888-8888-888888888888"
}Request URL
POST https://b2b.youhodler.com/api/webhook-subscriptionsRequest Body
{
"scope_ref": "enterprises/11111111-1111-4111-8111-111111111111",
"url": "https://api.acme.example/webhooks/b2b2x",
"event_types": [
"operations.withdrawal.settled.v1"
],
"secret": "replace-with-shared-secret"
}Created withdrawal destination
{
"asset": "USDC",
"created_at": "2026-05-01T10:00:00Z",
"crypto_routing": {
"asset": "USDC",
"destination": {
"address": "0xAbCd1234567890AbCd1234567890AbCd12345678",
"memo": null
},
"label": "My ETH wallet",
"network": "ethereum"
},
"fiat_routing": null,
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"label": "My ETH wallet",
"rail_class": "crypto",
"scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"status": "active",
"updated_at": "2026-05-01T10:00:00Z"
}Created webhook subscription
{
"created_at": "2026-05-01T10:00:00Z",
"etag": "2026-05-01T10:00:00Z",
"event_types": [
"operations.withdrawal.settled.v1"
],
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kind": "public",
"managed_by": null,
"resource": "webhook_subscription",
"scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"signing": "hmac",
"status": "active",
"updated_at": "2026-05-01T10:00:00Z",
"url": "https://example.com/webhooks"
}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
Request URL
POST https://b2b.youhodler.com/api/internal-transfersRequest Headers
Authorization: Bearer <token>
Idempotency-Key: 2db7da81-dc19-4781-8a8b-3a5cb460d142
Content-Type: application/jsonRequest Body
{
"amount": {
"value": "250000.00",
"currency": "USDC"
},
"source_ref": "master-accounts/22222222-2222-4222-8222-222222222222",
"target_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1"
}Accepted internal transfer
{
"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": {
"amount": {
"currency": "USDC",
"value": "250.00"
},
"source_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"target_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
},
"fee_summary": null,
"fill_rate": null,
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"principal_amount": {
"currency": "USDC",
"value": "250.00"
},
"settled_at": null,
"status": "admissible",
"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"
}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
Request URL
GET https://b2b.youhodler.com/api/client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1/balances?asset=USDCRequest URL
GET https://b2b.youhodler.com/api/webhook-subscriptions/ccccccc3-cccc-4ccc-8ccc-ccccccccccc3Client account balances
{
"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"
}
]
}Webhook subscription
{
"created_at": "2026-05-01T10:00:00Z",
"etag": "2026-05-01T10:00:00Z",
"event_types": [
"operations.withdrawal.settled.v1"
],
"id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"kind": "public",
"managed_by": null,
"resource": "webhook_subscription",
"scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"signing": "hmac",
"status": "active",
"updated_at": "2026-05-01T10:00:00Z",
"url": "https://example.com/webhooks"
}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.