Live Operations And Controls
Execute deposits, withdrawals, conversions, and ramp sessions under control.
This workflow is the runtime operating path for client-scoped and enterprise-scoped money movement, including previews, approval checks, status tracking, and asynchronous observation.
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. Preview and validate
Request URL
POST https://b2b.youhodler.com/api/fee-previewsRequest Body
{
"subject_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
"operation_type": "withdrawal_crypto",
"service_type": "withdrawal_crypto",
"principal_amount": {
"value": "1250.00",
"currency": "USDC"
}
}Request URL
GET https://b2b.youhodler.com/api/prices/indicative?from_asset=USDC&to_asset=EUR&amount_basis=from&from_amount=1250.00&account_ref=client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1Fee preview
{
"fee_preview": {
"binding": "non_binding",
"computed_at": "2026-05-01T10:00:00Z",
"enterprise_ca_version": 2,
"fee_summary": {
"components": [
{
"type": "platform_fee",
"amount": {
"currency": "USDC",
"value": "1.00"
},
"payee_ref": "master-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
],
"total": {
"currency": "USDC",
"value": "1.00"
}
},
"operation_type": "withdrawal_crypto",
"platform_ca_version": 1
}
}Indicative price
{
"amount_basis": "from",
"binding": false,
"calculated_at": "2026-05-01T10:00:00Z",
"expires_at": "2026-05-01T10:01:00.000Z",
"flow_type": "conversion",
"from_amount": {
"currency": "USDC",
"value": "250.00"
},
"from_asset": "USDC",
"indicative_price": {
"computed_at": "2026-05-01T10:00:00Z",
"price": "0.0000152",
"price_type": "indicative"
},
"pricing_mode": "indicative",
"to_amount": {
"currency": "BTC",
"value": "0.00380000"
},
"to_asset": "BTC"
}Preview endpoints should be treated as advisory preflight surfaces. The authoritative state still begins when a real operation resource is created.
2. Create the operation
Request URL
POST https://b2b.youhodler.com/api/withdrawalsRequest Headers
Authorization: Bearer <token>
Idempotency-Key: 5d17b978-e8ee-4f55-a313-7fe0f31f8535
X-Action-Token: <action token when required>
Content-Type: application/jsonRequest Body
{
"amount": {
"value": "1250.00",
"currency": "USDC"
},
"account_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
"destination_id": "bbbbbbb2-bbbb-4bbb-8bbb-bbbbbbbbbbb2",
"rail": "crypto"
}Accepted withdrawal
{
"account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
"approval_ref": null,
"created_at": "2026-05-01T10:00:00Z",
"failure_reason": null,
"family": "withdrawal",
"family_params": {},
"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": 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"
}Use idempotency on every mutating execution request. The operation id becomes the durable handle for later approval, tracking, and event correlation.
3. Resolve approvals with an eligible human
Use a token whose subject is an eligible human user. The service-account token
from setup cannot approve. Before deciding, satisfy the approval.decide MFA
assurance policy. On 401 insufficient_user_authentication, read the
WWW-Authenticate challenge (acr_values, max_age), authenticate at that
assurance and retry with the fresh human token. Platform staff always require MFA.
Request URL
GET https://b2b.youhodler.com/api/approvals?scope_ref=enterprises/11111111-1111-4111-8111-111111111111&status=pending&operation_id=eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5Approve the selected review
POST https://b2b.youhodler.com/api/approvals/fffffff6-ffff-4fff-8fff-fffffffffff6/approve
Authorization: Bearer <human_access_token>Request Body
{
"reason": "Reviewed by treasury operations and approved for release."
}Approval 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
}Approval after vote
{
"action_family": "withdrawal",
"collected_human_approvals": 1,
"created_at": "2026-05-01T10:00:00Z",
"decision": {
"decided_at": "2026-05-01T10:00:00Z",
"decided_by": {
"actor": null,
"approved_by": null,
"authenticated_principal": {
"id": "11111111-1111-4111-8111-111111111111",
"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": "11111111-1111-4111-8111-111111111111",
"kind": "user",
"tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}
},
"reason": "Approved after review"
},
"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": "approved",
"updated_at": "2026-05-01T10:00:00Z"
}Treat approval resources as first-class control-plane objects. They are not just side effects of an operation page; they are part of runtime governance.
4. Track status and final state
Request URL
GET https://b2b.youhodler.com/api/withdrawals/eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5Withdrawal state
{
"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
}Use polling selectively. In most integrations, direct reads are best for operator inspection or retry handling, while webhooks and events handle normal asynchronous processing.
5. Observe events and webhooks
Request URL
GET https://b2b.youhodler.com/api/events?aggregate_id=eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5Event 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
}The event stream is also the best cross-cutting surface for audit, replay, and operational traceability across multiple operation families.