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.
Operational Sequence
1. Preview and validate
Prices and fee previews. Inspect execution inputs before creating a real operation when the integration needs to show costs or conversion direction up front. This reduces operational surprises without mutating balances.
Request URL
POST https://business-api.youhodler.com/fee-previewsRequest Body
{
"subject_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
"operation_type": "withdrawal",
"service_type": "settlement",
"principal_amount": {
"amount": "1250.00",
"currency": "USDC"
},
"requested_at": "2026-04-28T13:40:00.000Z"
}Request URL
GET https://business-api.youhodler.com/prices/indicative?base_currency=USDC"e_currency=EUR&amount=1250.00Response
{
"fee_preview": {
"fee_components": [
{
"code": "platform_fee",
"amount": {
"amount": "7.50",
"currency": "USDC"
}
}
],
"summary": {
"total_fees": {
"amount": "7.50",
"currency": "USDC"
}
}
}
}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
Withdrawal, conversion, deposit, or ramp. Once the caller has an execution decision, create the real operation on the target `AccountRef`. The same lifecycle model powers withdrawals, conversions, deposits, and ramp sessions.
Request URL
POST https://business-api.youhodler.com/withdrawalsRequest Headers
Authorization: Bearer <token>
Idempotency-Key: 5d17b978-e8ee-4f55-a313-7fe0f31f8535
Content-Type: application/jsonRequest Body
{
"amount": {
"amount": "1250.00",
"currency": "USDC"
},
"account_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
"destination": {
"withdrawal_destination_id": "bbbbbbb2-bbbb-4bbb-8bbb-bbbbbbbbbbb2"
},
"rail": "crypto"
}Response
{
"id": "eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5",
"family": "withdrawal",
"status": "processing",
"account_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
"principal_amount": {
"amount": "1250.00",
"currency": "USDC"
},
"fee_summary": {
"total_fees": {
"amount": "7.50",
"currency": "USDC"
}
},
"fill_rate": null,
"failure_reason": null,
"approval_ref": null,
"subject_attribution": {
"subject_ref": "clients/88888888-8888-4888-8888-888888888888"
},
"family_params": {
"rail": "crypto",
"destination": {
"withdrawal_destination_id": "bbbbbbb2-bbbb-4bbb-8bbb-bbbbbbbbbbb2"
}
},
"created_at": "2026-04-28T13:44:20.000Z",
"updated_at": "2026-04-28T13:44:20.000Z"
}Use idempotency on every mutating execution request. The operation id becomes the durable handle for later approval, tracking, and event correlation.
3. Resolve approvals when required
Governed execution path. Some operations enter approval review instead of continuing immediately. Read the approval queue, then resolve the approval with an explicit approval or rejection action.
Request URL
GET https://business-api.youhodler.com/approvals?status=pending&operation_id=eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5Request Body
{
"reason": "Reviewed by treasury operations and approved for release."
}Response
{
"items": [
{
"id": "fffffff6-ffff-4fff-8fff-fffffffffff6",
"resource": "approval",
"status": "pending",
"operation": "withdrawal",
"operation_id": "eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5",
"decided_by": null,
"requirement_summary": {
"required_approvals": 1
},
"created_at": "2026-04-28T13:44:21.000Z",
"updated_at": "2026-04-28T13:44:21.000Z",
"expires_at": "2026-04-28T14:14:21.000Z"
}
],
"next_page_token": null
}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
Lifecycle visibility. After creation, read the operation resource directly when the caller needs the current status, a failure reason, or the final execution state.
Request URL
GET https://business-api.youhodler.com/withdrawals/eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5Response
{
"id": "eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5",
"family": "withdrawal",
"status": "completed",
"account_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
"principal_amount": {
"amount": "1250.00",
"currency": "USDC"
},
"fee_summary": {
"total_fees": {
"amount": "7.50",
"currency": "USDC"
}
},
"fill_rate": null,
"failure_reason": null,
"approval_ref": "approvals/fffffff6-ffff-4fff-8fff-fffffffffff6",
"subject_attribution": {
"subject_ref": "clients/88888888-8888-4888-8888-888888888888"
},
"family_params": {
"rail": "crypto"
},
"created_at": "2026-04-28T13:44:20.000Z",
"updated_at": "2026-04-28T13:47:18.000Z"
}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
Asynchronous integration. Event and webhook delivery should be the default machine-consumption path for operation progression. Polling is a fallback, not the main contract.
Request URL
GET https://business-api.youhodler.com/events?aggregate_type=operation&aggregate_id=eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5Response
{
"items": [
{
"id": "12121212-1212-4121-8121-121212121212",
"resource": "event",
"event_type": "operation.updated",
"schema_version": 1,
"occurred_at": "2026-04-28T13:47:18.000Z",
"published_at": "2026-04-28T13:47:18.100Z",
"aggregate": {
"type": "operation",
"id": "eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5"
},
"partition_key": "operations/eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5",
"trace_id": "23232323-2323-4232-8232-232323232323",
"subject_attribution": {
"subject_ref": "clients/88888888-8888-4888-8888-888888888888"
},
"enterprise_id": "11111111-1111-4111-8111-111111111111",
"data": {
"status": "completed"
},
"metadata": null
}
],
"next_page_token": null
}The event stream is also the best cross-cutting surface for audit, replay, and operational traceability across multiple operation families.