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

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

Request Body

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

Fee preview

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

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

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

Request Headers

required
Authorization: Bearer <token>
Idempotency-Key: 5d17b978-e8ee-4f55-a313-7fe0f31f8535
X-Action-Token: <action token when required>
Content-Type: application/json

Request Body

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

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": "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.

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
GET https://b2b.youhodler.com/api/approvals?scope_ref=enterprises/11111111-1111-4111-8111-111111111111&status=pending&operation_id=eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5

Approve the selected review

POST
POST https://b2b.youhodler.com/api/approvals/fffffff6-ffff-4fff-8fff-fffffffffff6/approve
Authorization: Bearer <human_access_token>

Request Body

application/json
{
  "reason": "Reviewed by treasury operations and approved for release."
}

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
}

Approval after vote

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

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
GET https://b2b.youhodler.com/api/withdrawals/eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5

Withdrawal state

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

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
GET https://b2b.youhodler.com/api/events?aggregate_id=eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5

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
}

The event stream is also the best cross-cutting surface for audit, replay, and operational traceability across multiple operation families.