Operations

This group covers real financial execution. Read it from preview into action: start with fee or price estimation, then move into mutating execution requests across withdrawal, conversion, and ramp families.

Preview And Execute

Create fee preview

Pre-execution fee check. Create a fee preview when the integration needs visible costs before submitting a real operation.

Request URL

POST
POST https://b2b.youhodler.com/api/fee-previews

Request Body

application/json
{
  "operation_type": "withdrawal_crypto",
  "principal_amount": {
    "currency": "USDC",
    "value": "100.00"
  },
  "requested_at": "2026-05-01T10:00:00Z",
  "service_type": "withdrawal_crypto",
  "settlement_amount": null,
  "subject_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
}

Response

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

Get indicative conversion price

Quoted conversion direction. Read the indicative price surface when the caller needs a directional conversion estimate before creating the real conversion request.

Request URL

GET
GET https://b2b.youhodler.com/api/prices/indicative?from_asset=USDC&to_asset=BTC&amount_basis=from&from_amount=250.00&account_ref=client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b

Response

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

Create withdrawal

Outbound account-scoped execution. Create a withdrawal when value should leave the operating account boundary through an explicit rail and destination.

Request URL

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

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

Create conversion

In-account asset change. Create a conversion when the operating account needs to change one asset into another through the canonical conversion family.

Request URL

POST
POST https://b2b.youhodler.com/api/conversions

Request Body

application/json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "from_amount": {
    "currency": "USD",
    "value": "250.00"
  },
  "to_currency": "BTC"
}

Response

application/json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "applied_rate": null,
  "approval_ref": null,
  "conversion_execution_id": null,
  "created_at": "2026-05-01T10:00:00Z",
  "failure_detail": null,
  "failure_reason": null,
  "family": "conversion",
  "fee_summary": null,
  "fee_transaction_ids": null,
  "fill_rate": null,
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "ledger_posted_target_amount": null,
  "leg_attempt_id": null,
  "posted_at": null,
  "principal_amount": {
    "currency": "USD",
    "value": "250.00"
  },
  "principal_transaction_id": null,
  "settled_at": null,
  "source_gross_amount": null,
  "source_principal_amount": 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"
    }
  },
  "target_amount": null,
  "target_currency": "BTC",
  "updated_at": "2026-05-01T10:00:00Z"
}

Create on-ramp session

Inbound purchase surface. Create an on-ramp session when a caller needs a guided fiat-to-asset acquisition flow tied back to an account boundary.

Request URL

POST
POST https://b2b.youhodler.com/api/on-ramp-sessions

Request Body

application/json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "amount": {
    "currency": "EUR",
    "value": "250.00"
  },
  "source_rail": "fiat",
  "target_currency": "USDC"
}

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": "on_ramp",
  "family_params": {
    "destination_payload": {},
    "destination_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "intermediate_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "source_amount": {
      "currency": "EUR",
      "value": "250.00"
    },
    "source_rail": "fiat",
    "target_currency": "USDC"
  },
  "fee_summary": null,
  "fill_rate": null,
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "principal_amount": {
    "currency": "EUR",
    "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"
}

Create off-ramp session

Outbound liquidation surface. Create an off-ramp session when an asset position needs a guided asset-to-fiat exit path.

Request URL

POST
POST https://b2b.youhodler.com/api/off-ramp-sessions

Request Body

application/json
{
  "account_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "amount": {
    "currency": "USDC",
    "value": "250.00"
  },
  "destination": {
    "destination": {
      "bank_coordinates": {
        "account_holder_name": "Acme Treasury",
        "bank_name": "Demo Bank",
        "bic": "NWBKGB2L",
        "country": "GB",
        "iban": "GB29NWBK60161331926819",
        "scheme": "iban"
      },
      "beneficiary_name": "Acme Treasury",
      "currency": "EUR",
      "fiat_rail": "sepa_credit_transfer",
      "method": "bank_transfer",
      "reference_hint": null
    },
    "fiat_rail": "sepa_credit_transfer",
    "method": "bank_transfer",
    "payment_reference": "RF18539007547034",
    "route_owner_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "withdrawal_destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
  },
  "target_currency": "EUR",
  "target_rail": "fiat"
}

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": "off_ramp",
  "family_params": {
    "destination_payload": {
      "destination": {
        "bank_coordinates": {
          "account_holder_name": "Acme Treasury",
          "bank_name": "Demo Bank",
          "bic": "NWBKGB2L",
          "country": "GB",
          "iban": "GB29NWBK60161331926819",
          "scheme": "iban"
        },
        "beneficiary_name": "Acme Treasury",
        "currency": "EUR",
        "fiat_rail": "sepa_credit_transfer",
        "method": "bank_transfer",
        "reference_hint": null
      },
      "fiat_rail": "sepa_credit_transfer",
      "method": "bank_transfer",
      "payment_reference": "RF18539007547034",
      "withdrawal_destination_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "intermediate_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "source_amount": {
      "currency": "USDC",
      "value": "250.00"
    },
    "source_ref": "client-accounts/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "target_currency": "EUR",
    "target_rail": "fiat"
  },
  "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"
}