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
Request URL
GET https://b2b.youhodler.com/api/master-accounts/22222222-2222-4222-8222-222222222222/balances?asset=USDCRequest URL
GET https://b2b.youhodler.com/api/withdrawals?account_ref=client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1&page_size=20Master account balances
{
"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
{
"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
Request URL
POST https://b2b.youhodler.com/api/internal-transfersRequest Body
{
"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
{
"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
Request URL
GET https://b2b.youhodler.com/api/approvals?scope_ref=enterprises/11111111-1111-4111-8111-111111111111&status=pendingRequest URL
GET https://b2b.youhodler.com/api/events?aggregate_id=88888888-8888-4888-8888-888888888888Approval page
{
"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
{
"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.
Request URL
POST https://b2b.youhodler.com/api/client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1/suspendRequest Body
{
"reason": "Client account is being wound down after balance exit."
}Suspended 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": "suspended",
"updated_at": "2026-05-01T10:00:00Z"
}Request URL
POST https://b2b.youhodler.com/api/clients/88888888-8888-4888-8888-888888888888/suspendRequest Body
{
"reason": "Downstream operating perimeter is being offboarded after balance exit."
}Suspended 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": "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
Request URL
POST https://b2b.youhodler.com/api/service-accounts/33333333-3333-4333-8333-333333333333/revokeRequest Body
{
"reason": "Tenant offboarding is complete. Revoke non-human execution access."
}Revoked service account
{
"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.