# Simulate a balance top-up

Simulates a top-up so that a balance can be used to fund transfers and/or card spend.

Endpoint: POST /simulation/balance/topup
Version: 2026Q4
Security: UserToken

## Security:

  - `UserToken` (unknown)
    http bearer JWT

## Header parameters:

  - `X-External-Correlation-Id` (string)
    Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. [Learn more](/guides/developer/headers/correlation-id).

## Request fields (application/json):

  - `profileId` (integer, required)
    The profile ID linked to the balance account.

  - `balanceId` (integer, required)
    The ID of the balance account that is going to receive the funds.

  - `currency` (string, required)
    The currency to top up the balance account in. Must be the same currency as the balance account.

  - `amount` (number, required)
    The amount to top up the balance account with.

  - `channel` (string)
    Type of top-up. Not providing a channel will default to `CARD`.
    Enum: "TRANSFER", "CARD"

## Response 200:

  - `200` (unknown)
    Simulated balance top-up result.

## Response 200 fields (application/json):

  - `transactionId` (integer)
    The ID of the top-up transaction.

  - `state` (string)
    The state of the transaction. `COMPLETED` is always returned when using this endpoint.

  - `balancesAfter` (array)

  - `balancesAfter.id` (integer)
    The ID of the balance account.

  - `balancesAfter.value` (number)
    The new amount available in the balance account.

  - `balancesAfter.currency` (string)
    The currency of the balance account.

## Response 200 headers (application/json):

  - `X-External-Correlation-Id` (string)
    Echoed back when `X-External-Correlation-Id` was included in the request. [Learn more](/guides/developer/headers/correlation-id).
    Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

  - `x-trace-id` (string)
    Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.
    Example: fba501b6d453b96789f52338f019341f

## Response 429:

  - `429` (unknown)
    Rate limit exceeded. Retry after the number of seconds specified in the `Retry-After` header.

## Response 429 headers (application/json):

  - `Retry-After` (integer)
    Number of seconds to wait before retrying the request.
    Example: 5

  - `X-Rate-Limited-By` (string)
    Identifies the rate limiter that triggered the 429 response.
    Example: wise-public-api

  - `X-External-Correlation-Id` (string)
    Echoed back when `X-External-Correlation-Id` was included in the request. [Learn more](/guides/developer/headers/correlation-id).
    Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

  - `x-trace-id` (string)
    Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.
    Example: fba501b6d453b96789f52338f019341f