YOUHODLERBusiness API
Get access
View as Markdown

postCreate withdrawal

Required capabilitywithdrawals.create

Creates a withdrawal operation. For crypto requests, bind either a stored withdrawal destination (destination_id) or a one-time inline destination ({address, memo} plus network) — exactly one crypto destination path must be present. For fiat requests, bind a stored fiat withdrawal destination by its withdrawal_destination_id, resolved within the supplied account_ref scope; the canonical bank routing and the authoritative owner topology are sourced from the stored destination, never from the request body. Both rails flow through the same create path: a fiat withdrawal is admitted here and gated downstream solely by fiat-rails runtime readiness at dispatch time (it is no longer short-circuited at the edge). Successful responses return the operation snapshot — for an immediately admitted withdrawal the response may carry status = "executing" once operation-flow has written that state. Idempotent on Idempotency-Key or client_idempotency_key. Human callers must obtain a step-up confirmation via POST /action-tokens and submit it in the X-Action-Token header; service principals are exempt.

Request

Request URL

POST
POST /withdrawals

Request Body

application/json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "amount": {
    "currency": "EUR",
    "value": "100.00"
  },
  "rail": "fiat",
  "withdrawal_destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}

Responses

Response

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

Request accepted for asynchronous processing. Poll the returned operation ID to track status transitions.

Related endpoints