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

Downstream topology resource. Create the client before provisioning additional accounts, payout destinations, or client-scoped liquidity. Keep the returned client id for account creation.

Request URL

POST
POST https://b2b.youhodler.com/api/clients

Request Body

application/json
{
  "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

201 application/json
{
  "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

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
POST https://b2b.youhodler.com/api/client-accounts

Request Body

application/json
{
  "display_name": "USDC Settlement Account",
  "metadata": {
    "purpose": "settlement",
    "asset": "USDC"
  },
  "scope_ref": "clients/88888888-8888-4888-8888-888888888888"
}

Created client account

201 application/json
{
  "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

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
POST https://b2b.youhodler.com/api/withdrawal-destinations

Request Body

application/json
{
  "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
POST https://b2b.youhodler.com/api/webhook-subscriptions

Request Body

application/json
{
  "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

201 application/json
{
  "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

201 application/json
{
  "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

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
POST https://b2b.youhodler.com/api/internal-transfers

Request Headers

required
Authorization: Bearer <token>
Idempotency-Key: 2db7da81-dc19-4781-8a8b-3a5cb460d142
Content-Type: application/json

Request Body

application/json
{
  "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

202 application/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": {
    "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

Readiness check. Before operational workloads start, read the client-account balance rows and confirm that the webhook subscription is active. This makes the downstream perimeter observable before live execution begins.

Request URL

GET
GET https://b2b.youhodler.com/api/client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1/balances?asset=USDC

Request URL

GET
GET https://b2b.youhodler.com/api/webhook-subscriptions/ccccccc3-cccc-4ccc-8ccc-ccccccccccc3

Client account balances

200 application/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"
    }
  ]
}

Webhook subscription

200 application/json
{
  "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.