> ## Documentation Index > Fetch the complete documentation index at: https://developer.finogates.com/llms.txt > Use this file to discover all available pages before exploring further. # Freeze Funds in a Wallet > Freeze part of a wallet's balance, addressed by **wallet id**. The amount moves out of the wallet's **available** balance into a **held** bucket: ``available`` drops, but ``current`` is unchanged — the money hasn't left the wallet, it just can't be spent normally. Freeze happens immediately (no approval). Held funds can later be spent by any wallet-sourced payment (Wallet → Bank, Wallet → Wallet) sent with ``from_hold: true``, or returned to available via **Unfreeze Funds**. Freezes accumulate — freezing twice adds up. Optionally pass a ``reason`` and ``reference`` — both are recorded on the ledger and audit trail and surfaced in **List Wallet Holds**. ## OpenAPI ````yaml POST /v1/platform/wallets/by-id/{wallet_id}/holds openapi: 3.1.0 info: title: Finogate Platform API v1 version: 0.1.0 servers: - url: https://api-sandbox.finogates.com description: Sandbox - url: https://api.finogates.com description: Production security: [] tags: - name: auth - name: users - name: payees - name: verification - name: bank accounts - name: card processing - name: digital-assets - name: international - name: fees - name: onboarding - name: pending-applications - name: wallets - name: payments - name: document mailing - name: merchant onboarding - name: catalog - name: webhooks - name: screening - name: Platform - File Scanning - name: phone-numbers - name: sms - name: calls - name: listings - name: Card Transfers - name: embed-tokens paths: /v1/platform/wallets/by-id/{wallet_id}/holds: post: tags: - wallets summary: Freeze Funds in a Wallet description: >- Freeze part of a wallet's balance, addressed by **wallet id**. The amount moves out of the wallet's **available** balance into a **held** bucket: ``available`` drops, but ``current`` is unchanged — the money hasn't left the wallet, it just can't be spent normally. Freeze happens immediately (no approval). Held funds can later be spent by any wallet-sourced payment (Wallet → Bank, Wallet → Wallet) sent with ``from_hold: true``, or returned to available via **Unfreeze Funds**. Freezes accumulate — freezing twice adds up. Optionally pass a ``reason`` and ``reference`` — both are recorded on the ledger and audit trail and surfaced in **List Wallet Holds**. operationId: create_wallet_hold_v1_platform_wallets_by_id__wallet_id__holds_post parameters: - name: wallet_id in: path required: true schema: type: string format: uuid description: The wallet to freeze funds on. examples: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 title: Wallet Id description: The wallet to freeze funds on. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WalletHoldCreate' responses: '201': description: Wallet balances after the freeze, plus the amount moved. content: application/json: schema: $ref: '#/components/schemas/CommonResponse' example: status_code: 201 data: wallet_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 currency: USD amount: '250.00' available: '750.00' held: '250.00' current: '1000.00' reference: order-6841 query_generated_time: 1712847600000 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - _AuthenticatedBearer: [] components: schemas: WalletHoldCreate: properties: amount: anyOf: - type: number exclusiveMinimum: 0 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Amount description: Amount to freeze, in major currency units. currency: type: string maxLength: 3 minLength: 3 title: Currency default: USD reason: anyOf: - type: string maxLength: 500 - type: 'null' title: Reason description: Optional human-readable purpose, recorded on the ledger + audit log. reference: anyOf: - type: string maxLength: 120 - type: 'null' title: Reference description: Optional caller reference/idempotency trace for the hold. type: object required: - amount title: WalletHoldCreate description: >- Freeze (hold) part of a wallet's available balance. Moves ``amount`` from the wallet's ``available`` balance into its frozen ``hold`` bucket: ``available`` drops, ``current`` is unchanged (the money hasn't left the wallet). The frozen funds can later be spent by a payment with ``from_hold=true`` or returned to ``available`` via a release. This is a partial-amount hold — distinct from the whole-wallet ``is_frozen`` block. CommonResponse: properties: status_code: type: integer title: Status Code description: HTTP status code for the response. data: title: Data description: Payload or error details. query_generated_time: type: integer title: Query Generated Time description: >- UTC timestamp (milliseconds since epoch) when response was generated. type: object required: - status_code - data - query_generated_time title: CommonResponse description: |- Standard response wrapper for single-object responses and errors. Generic over the payload type. A route that declares ``CommonResponse[SomeModel]`` gets the real ``data`` schema rendered in OpenAPI/Swagger; a bare ``CommonResponse`` leaves ``data`` untyped. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: _AuthenticatedBearer: type: oauth2 flows: password: scopes: {} tokenUrl: /v1/platform/auth/token ````