# Distribution And Liquidity

> How to onboard clients, set up funding endpoints and withdrawal destinations, and manage liquidity across accounts.

Source: https://business-api-docs.youhodler.com/docs/workflows/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.

> **Business impact:** `Client` defines the downstream operating perimeter. `ClientAccount` defines the downstream financial execution perimeter. Liquidity should only be moved after both are in place and the outbound or inbound rails are prepared.

## 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.

The response can include the default client account ref. Keep it, because the next steps will usually branch from that account boundary.

[API Reference: Create client (POST)](/docs/api/reference/clients/clients-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/clients
```
**Request Body — application/json**
```json
{
  "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"
  }
}
```
**201 Client Created**

```json
{
  "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\""
}
```

**409 Conflict**

```json
{
  "code": "state_conflict",
  "message": "A client with the requested external_id already exists under the same enterprise."
}
```

### 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.

Keep the created client account ids handy. They become the `account_ref` targets for internal transfers, withdrawals, conversions, and ramp sessions.

[API Reference: Create client account (POST)](/docs/api/reference/client-accounts/client-accounts-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/client-accounts
```
**Request Body — application/json**
```json
{
  "client": "clients/88888888-8888-4888-8888-888888888888",
  "display_name": "USDC Settlement Account",
  "metadata": {
    "purpose": "settlement",
    "asset": "USDC"
  }
}
```
**201 Client Account Created**

```json
{
  "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\""
}
```

**409 Conflict**

```json
{
  "code": "state_conflict",
  "message": "The requested client account shape already exists for this client."
}
```

### 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.

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.

[API Reference: Create withdrawal destination (POST)](/docs/api/reference/withdrawal-destinations/withdrawal-destinations-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/withdrawal-destinations
```
**Request Body — application/json**
```json
{
  "rail_class": "crypto",
  "idempotency_key": "4b3d6e0c-f4a5-47f4-a5ab-4d568d0a9f10",
  "crypto_routing": {
    "asset": "USDC",
    "network": "ethereum",
    "address": "0x5F8d1D0B3D6A7f7A4d0F8fB23e8f420f4bB01234"
  }
}
```
**Request Body — application/json**
```json
{
  "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"
}
```
**201 Destination Created**

```json
{
  "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
}
```

**201 Webhook Created**

```json
{
  "id": "ccccccc3-cccc-4ccc-8ccc-ccccccccccc3",
  "resource": "webhook_subscription",
  "enterprise_id": "11111111-1111-4111-8111-111111111111",
  "url": "https://api.acme.example/webhooks/b2b2x",
  "event_types": [
    "operation.created",
    "operation.updated",
    "approval.updated"
  ],
  "status": "enabled",
  "created_at": "2026-04-28T13:18:20.000Z",
  "updated_at": "2026-04-28T13:18:20.000Z",
  "etag": "W/\"webhook-1\""
}
```

### 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.

Internal transfers are also the same family you will later use for rebalancing or returning liquidity during settlement and suspension.

[API Reference: Create internal transfer (POST)](/docs/api/reference/internal-transfers/internal-transfers-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/internal-transfers
```
**Request Headers — required**
```json
Authorization: Bearer <token>
Idempotency-Key: 2db7da81-dc19-4781-8a8b-3a5cb460d142
Content-Type: application/json
```
**Request Body — application/json**
```json
{
  "amount": {
    "amount": "250000.00",
    "currency": "USDC"
  },
  "source_ref": "master-accounts/22222222-2222-4222-8222-222222222222",
  "target_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1"
}
```
**202 Transfer Accepted**

```json
{
  "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"
}
```

**422 Not Admissible**

```json
{
  "code": "not_admissible",
  "message": "The requested transfer cannot proceed under the current topology or policy posture."
}
```

### 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.

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.

[API Reference: List client account balances (GET)](/docs/api/reference/balances/client-accounts-balances)

**Request URL — GET**
```http
GET https://business-api.youhodler.com/client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1/balances?asset=USDC
```
**Request URL — POST**
```http
POST https://business-api.youhodler.com/webhook-endpoints/ccccccc3-cccc-4ccc-8ccc-ccccccccccc3/enable
```
**200 Balance Rows**

```json
{
  "items": [
    {
      "asset": "USDC",
      "available": "250000.00",
      "pending_in": "0.00",
      "pending_out": "0.00"
    }
  ]
}
```

**200 Webhook Enabled**

```json
{
  "id": "ccccccc3-cccc-4ccc-8ccc-ccccccccccc3",
  "resource": "webhook_subscription",
  "enterprise_id": "11111111-1111-4111-8111-111111111111",
  "url": "https://api.acme.example/webhooks/b2b2x",
  "event_types": [
    "operation.created",
    "operation.updated",
    "approval.updated"
  ],
  "status": "enabled",
  "created_at": "2026-04-28T13:18:20.000Z",
  "updated_at": "2026-04-28T13:24:10.000Z",
  "etag": "W/\"webhook-2\""
}
```