# Clients And Accounts

> API Kickstart for clients, client accounts, balances, and internal transfers.

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

> **Why this group exists:** `clients` creates the downstream operating entity. `client-accounts` creates the client-scoped execution boundary. `balances` and `internal-transfers` expose the visibility and liquidity movement that make that boundary usable.

## Downstream Perimeter And Liquidity

### Create client

Downstream topology resource. Create a client before any client-scoped account, balance, or operation work can exist.

[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
{
  "display_name": "Acme Corp",
  "external_id": "ext-client-0042",
  "metadata": {
    "crm_id": "CRM-001",
    "tier": "premium"
  },
  "scope_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```
**201 Client Created**

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

[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
{
  "display_name": "Operating Account EUR",
  "scope_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```
**201 Client Account Created**

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

[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/aaa111/balances?asset=USD
```
**200 Balance Rows**

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

[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 Body — application/json**
```json
{
  "amount": {
    "currency": "USDC",
    "value": "250.00"
  },
  "source_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "target_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
```
**202 Transfer Accepted**

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

[API Reference: Get internal transfer (GET)](/docs/api/reference/internal-transfers/internal-transfers-get)

**Request URL — GET**
```http
GET https://business-api.youhodler.com/internal-transfers/it_456
```
**200 Internal Transfer**

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