Settlement And Suspension

Review balances, unwind exposure, and close resources deliberately.

This workflow covers the tail of the lifecycle: balance review, liquidity return, governance cleanup, and resource suspension or closure across clients, accounts, and actors.

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. Inspect balances and recent operation state

Operational review. Start with actual owner balances and recent operation state before changing lifecycle or access. This avoids suspending resources while financial exposure is still unresolved.

Request URL

GET
GET https://b2b.youhodler.com/api/master-accounts/22222222-2222-4222-8222-222222222222/balances?asset=USDC

Request URL

GET
GET https://b2b.youhodler.com/api/withdrawals?account_ref=client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1&page_size=20

Master account balances

200 application/json
{
  "items": [
    {
      "asset": "USDC",
      "available": "950.00",
      "held": "50.00",
      "overdraft_headroom": "400.00",
      "overdraft_limit": "500.00",
      "overdraft_used": "100.00",
      "owner_ref": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "owner_subtype": "master_account",
      "total": "1000.00",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ]
}

Withdrawal page

200 application/json
{
  "items": [
    {
      "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "approval_ref": null,
      "created_at": "2026-05-01T10:00:00Z",
      "destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "dispatch_attempt_id": null,
      "failure_reason": null,
      "family": "withdrawal",
      "family_flow_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "fee_summary": {
        "components": [
          {
            "amount": {
              "currency": "USDC",
              "value": "1.00"
            },
            "kind": "network_fee"
          }
        ],
        "total": {
          "currency": "USDC",
          "value": "1.00"
        }
      },
      "fee_transaction_ids": [],
      "fill_rate": null,
      "hold_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "leg_attempt_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "network": "ethereum",
      "principal_amount": {
        "currency": "USDC",
        "value": "250.00"
      },
      "principal_transaction_id": null,
      "rail": "ethereum",
      "rail_class": "crypto",
      "release_transaction_id": null,
      "settled_at": null,
      "settlement_evidence": null,
      "status": "executing",
      "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",
      "withdrawal_attempt_id": null
    }
  ],
  "next_page_token": null
}

If both enterprise and client balances are in scope, read both before deciding which balances should be returned, settled, or left in place.

2. Return or rebalance liquidity

Internal transfers and withdrawals. Return client-scoped balances to the desired operating boundary before closing accounts or removing access. Rebalancing first keeps lifecycle changes from masking stranded funds.

Request URL

POST
POST https://b2b.youhodler.com/api/internal-transfers

Request Body

application/json
{
  "amount": {
    "value": "50000.00",
    "currency": "USDC"
  },
  "source_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
  "target_ref": "master-accounts/22222222-2222-4222-8222-222222222222"
}

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"
}

The same family can rebalance liquidity between internal account boundaries or return balances back to the enterprise treasury perimeter.

3. Resolve approvals and inspect event consumers

Governance cleanup. Before lifecycle shutdown, check for pending approvals and review recent event flow. This prevents closing a resource while governance or downstream consumers still expect activity.

Request URL

GET
GET https://b2b.youhodler.com/api/approvals?scope_ref=enterprises/11111111-1111-4111-8111-111111111111&status=pending

Request URL

GET
GET https://b2b.youhodler.com/api/events?aggregate_id=88888888-8888-4888-8888-888888888888

Approval page

200 application/json
{
  "items": [
    {
      "action_family": "withdrawal",
      "collected_human_approvals": 0,
      "created_at": "2026-05-01T10:00:00Z",
      "decision": null,
      "expires_at": "2026-05-02T10:00:00Z",
      "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "initiated_by": {
        "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"
        }
      },
      "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "requirement_snapshot": {
        "authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "expires_at": "2026-05-02T10:00:00Z",
        "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "initiator_cannot_approve": true,
        "reason_code": "high_value",
        "required_human_approvals": 1,
        "requirement_key": "withdrawal_approval",
        "source": "policy"
      },
      "resource": "approval",
      "status": "pending",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "next_page_token": null
}

Event page

200 application/json
{
  "items": [
    {
      "aggregate": {
        "type": "withdrawal",
        "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
      },
      "data": {
        "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "failure_reason": null,
        "family": "withdrawal",
        "fee_summary": {
          "components": [
            {
              "amount": {
                "currency": "USDC",
                "value": "1.00"
              },
              "kind": "network_fee"
            }
          ],
          "total": {
            "currency": "USDC",
            "value": "1.00"
          }
        },
        "fill_rate": null,
        "occurred_at": "2026-05-01T10:00:00Z",
        "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "principal_amount": {
          "currency": "USDC",
          "value": "250.00"
        },
        "scope_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "status": "settled"
      },
      "event_type": "operations.withdrawal.settled.v1",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "metadata": null,
      "occurred_at": "2026-05-01T10:00:00Z",
      "partition_key": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "published_at": "2026-05-01T10:00:00Z",
      "resource": "event",
      "schema_version": 1,
      "scope_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "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"
        }
      },
      "trace_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    }
  ],
  "next_page_token": null
}

If lifecycle changes need to be auditable, pair approval review with event review so operator actions and system state remain correlated.

4. Suspend or close resources

Suspend the client account first, then its parent client. Client suspension does not cascade; account suspension is refused once its parent is inactive.

Lifecycle transitions. Suspend or close clients and client accounts only after the financial boundary is under control. Apply the lifecycle sequence intentionally instead of broad revocation first.

Request URL

POST
POST https://b2b.youhodler.com/api/client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1/suspend

Request Body

application/json
{
  "reason": "Client account is being wound down after balance exit."
}

Suspended 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": "suspended",
  "updated_at": "2026-05-01T10:00:00Z"
}

Request URL

POST
POST https://b2b.youhodler.com/api/clients/88888888-8888-4888-8888-888888888888/suspend

Request Body

application/json
{
  "reason": "Downstream operating perimeter is being offboarded after balance exit."
}

Suspended 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": "suspended",
  "updated_at": "2026-05-01T10:00:00Z"
}

Suspension is useful when the resource may return later. Closure is the stronger terminal state and should usually come after a successful wind-down.

5. Revoke access surfaces

Final access cleanup. Revoke service accounts and other access paths only after financial state, approvals, and lifecycle posture have been intentionally wound down.

Request URL

POST
POST https://b2b.youhodler.com/api/service-accounts/33333333-3333-4333-8333-333333333333/revoke

Request Body

application/json
{
  "reason": "Tenant offboarding is complete. Revoke non-human execution access."
}

Revoked service account

200 application/json
{
  "description": "Withdrawal automation account",
  "created_at": "2026-05-01T10:00:00Z",
  "current_secret_expires_at": "2026-05-02T10:00:00Z",
  "etag": "00a01034334947d85285ad894a952245ded22dac3b2916b827a159f8f4233ef3",
  "external_id": "sa-ext-001",
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "managed_by": null,
  "parent_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "previous_secret_expires_at": null,
  "principal_ref": "service-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "resource": "service_account",
  "status": "revoked",
  "updated_at": "2026-05-01T10:00:00Z"
}

Access revocation is the last perimeter action. If it happens too early, the integration can lose the ability to inspect, reconcile, or finish closure safely.