# Transfer Subaccount Balance

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /v1/subaccounts/transfers:
    post:
      summary: Transfer Subaccount Balance
      deprecated: false
      description: >-
        Transfers an amount of a single currency from one account to another,
        where both accounts belong to the authenticated account holder (the main
        account or any of its subaccounts).


        The debit is applied to the source account first; if the credit to the
        destination fails, the debit is automatically rolled back.


        **Required API scope:** `SUBACCOUNT_TRANSFER`. The API key presented in
        the `Authorization: Bearer <token>` header must carry this permission
        (keys with `UI_HOLDER` / `UI_ACCOUNT` permissions are also authorised).
        The account holder must be active. This endpoint is not rate-limited.


        Both `source_account_id` and `destination_account_id` must be owned by
        the caller and must be different from one another. `amount` must be sent
        as a JSON string. Amount precision is truncated to 8 decimal places (3
        for SHIB, PEPE and BTT). The available balance of the source account is
        checked before the transfer.



        :::info[Note]

        This endpoint does not allow transfers to and from the `instant-trade`
        account.

        :::
      operationId: transferSubaccountBalance
      tags:
        - One Trading Public REST API/Funding
        - Subaccounts
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubaccountTransferRequest'
            examples:
              default:
                value:
                  amount: '100.00'
                  currency: EUR
                  source_account_id: 8f2b6c1e-0a9d-4c7e-9b21-2f5d3a1c4e6a
                  destination_account_id: 3c7a1d40-6b2e-4f88-9a10-7e5c2b9f0d13
                summary: Move 100 EUR from a subaccount to the main account
      responses:
        '200':
          x-apidog-name: OK
          description: >-
            Transfer completed. Returns the outgoing transfer record;
            `account_holder` holds the source account ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubaccountTransferResponse'
              example:
                transfer:
                  account_holder: 8f2b6c1e-0a9d-4c7e-9b21-2f5d3a1c4e6a
                  transfer_id: 5b9e2f10-8c4a-4d21-b6f7-1a2c3d4e5f60
                  source_account_id: 8f2b6c1e-0a9d-4c7e-9b21-2f5d3a1c4e6a
                  destination_account_id: 3c7a1d40-6b2e-4f88-9a10-7e5c2b9f0d13
                  currency: EUR
                  amount: '100.00'
                  time: '2026-07-03T10:15:30.000Z'
          headers: {}
        '400':
          x-apidog-name: Bad Request
          description: >-
            Validation error. `error` holds a human-readable message. Returned
            when the body is not valid JSON, a required field is missing, the
            amount is malformed, source and destination are identical, the
            source account has no balance in the currency (also the case for an
            unknown or lower-case currency code), the source balance is
            insufficient, or a BLP account would drop below its EUR threshold.
          content:
            application/json:
              schema: &ref_0
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                '2':
                  summary: invalidJson
                  value:
                    error: Invalid JSON.
                '3':
                  summary: missingAmount
                  value:
                    error: amount is required.
                '4':
                  summary: invalidAmount
                  value:
                    error: invalid amount.
                '5':
                  summary: missingCurrency
                  value:
                    error: currency is required.
                '6':
                  summary: sameAccount
                  value:
                    error: >-
                      source_account_id and destination_account_id cannot be the
                      same.
                '7':
                  summary: noBalance
                  value:
                    error: >-
                      No balance returned for account
                      8f2b6c1e-0a9d-4c7e-9b21-2f5d3a1c4e6a for currency EUR
                '8':
                  summary: insufficientBalance
                  value:
                    error: >-
                      Insufficient balance in account
                      8f2b6c1e-0a9d-4c7e-9b21-2f5d3a1c4e6a for a transfer of
                      100.00 EUR
                '9':
                  summary: blpThreshold
                  value:
                    error: >-
                      BLP account 8f2b6c1e-0a9d-4c7e-9b21-2f5d3a1c4e6a would be
                      below the threshold of 1000 EUR after the transfer
          headers: {}
        '401':
          description: >-
            Unauthorized. The token was accepted by the gateway but rejected by
            the endpoint: `UNAUTHORIZED`, or `INVALID_REQUEST_SIGNATURE` when
            the API key requires signed requests and the signature is missing or
            invalid.
          content:
            application/json:
              schema: *ref_0
              examples:
                '10':
                  summary: Unauthorized
                  value:
                    error: UNAUTHORIZED
                    error_message: Unauthorized access
                '11':
                  summary: Invalid signature
                  value:
                    error: INVALID_REQUEST_SIGNATURE
                    error_message: The request signature is missing or invalid
          headers: {}
          x-apidog-name: Unauthorized
        '403':
          x-apidog-name: Forbidden
          description: >-
            Permission denied. `{"error":"Permission denied."}` when the account
            holder is not active or one of the accounts is not owned by the
            caller. `PERMISSION_DENIED` (with `error_message`) when the API key
            lacks the `SUBACCOUNT_TRANSFER` scope,
            `EXCHANGE_ACCOUNT_NOT_PROVISIONED` when the account has no exchange
            account yet, and the gateway returns `{"message":"Forbidden"}` for a
            missing, invalid or revoked token.
          content:
            application/json:
              schema:
                oneOf:
                  - *ref_0
                  - $ref: '#/components/schemas/GatewayError'
              examples:
                '12':
                  summary: default
                  value:
                    error: Permission denied.
                '13':
                  summary: missingScope
                  value:
                    error: PERMISSION_DENIED
                    error_message: Permission denied
                '14':
                  summary: notProvisioned
                  value:
                    error: EXCHANGE_ACCOUNT_NOT_PROVISIONED
                    error_message: >-
                      The account is authenticated but has no exchange account
                      yet
                '15':
                  summary: gateway
                  value:
                    message: Forbidden
          headers: {}
        '422':
          x-apidog-name: Parameter Error
          description: >-
            Unprocessable. The exchange rejected the debit: `INSUFFICIENT_FUNDS`
            when the source account no longer has enough funds at the time of
            the debit, or `USER_MGMT_USER_IN_DERISK` when the user is currently
            in a de-risk state.
          content:
            application/json:
              schema: *ref_0
              examples:
                '16':
                  summary: insufficientFunds
                  value:
                    error: INSUFFICIENT_FUNDS
                '17':
                  summary: derisk
                  value:
                    error: USER_MGMT_USER_IN_DERISK
          headers: {}
        '500':
          x-apidog-name: Server Error
          description: Server error or server configuration error.
          content:
            application/json:
              schema: *ref_0
              examples:
                '18':
                  summary: default
                  value:
                    error: Server error.
                '19':
                  summary: misconfigured
                  value:
                    error: Server configuration error.
          headers: {}
      security:
        - bearer: []
      x-apidog-folder: One Trading Public REST API/Funding
      x-apidog-status: released
      x-run-in-apidog: https://app.eu.apidog.com/web/project/349694/apis/api-4422334-run
components:
  schemas:
    SubaccountTransferRequest:
      type: object
      required:
        - amount
        - currency
        - source_account_id
        - destination_account_id
      properties:
        amount:
          type: string
          description: >-
            Amount to transfer, as a JSON string holding a decimal (a JSON
            number is not accepted). Must match `^[0-9,.]*$`. Truncated to 8
            decimal places (3 for SHIB, PEPE, BTT).
          examples:
            - '100.00'
        currency:
          type: string
          description: Upper-case currency (asset) code of the balance to move, e.g. `EUR`.
          examples:
            - EUR
        source_account_id:
          type: string
          description: >-
            Account to debit: the main account ID or a subaccount ID. Must be
            owned by the caller.
          examples:
            - 8f2b6c1e-0a9d-4c7e-9b21-2f5d3a1c4e6a
        destination_account_id:
          type: string
          description: >-
            Account to credit: the main account ID or a subaccount ID. Must be
            owned by the caller and different from `source_account_id`.
          examples:
            - 3c7a1d40-6b2e-4f88-9a10-7e5c2b9f0d13
      x-apidog-orders:
        - amount
        - currency
        - source_account_id
        - destination_account_id
      x-apidog-folder: ''
      x-apidog-ignore-properties: []
    SubaccountTransferResponse:
      type: object
      properties:
        transfer:
          type: object
          properties:
            account_holder:
              type: string
              description: ID of the source account (same value as `source_account_id`).
            transfer_id:
              type: string
              description: Unique identifier of the outgoing transfer record.
            source_account_id:
              type: string
              description: Account that was debited.
            destination_account_id:
              type: string
              description: Account that was credited.
            currency:
              type: string
              description: Currency code as sent in the request.
            amount:
              type: string
              description: Amount transferred, after truncation, as a decimal string.
            time:
              type: string
              format: date-time
              description: ISO-8601 timestamp at which the transfer was recorded.
          x-apidog-orders:
            - account_holder
            - transfer_id
            - source_account_id
            - destination_account_id
            - currency
            - amount
            - time
          required:
            - account_holder
            - transfer_id
            - source_account_id
            - destination_account_id
            - currency
            - amount
            - time
          x-apidog-ignore-properties: []
      x-apidog-orders:
        - transfer
      x-apidog-folder: ''
      required:
        - transfer
      x-apidog-ignore-properties: []
    ErrorResponse:
      type: object
      description: >-
        Error body. `error` is a machine-readable code (e.g.
        `INVALID_INSTRUMENT_CODE`) on most endpoints; a few older endpoints
        return a human-readable message in `error` instead and omit
        `error_message`.
      properties:
        error:
          type: string
          description: Error code (or, on older endpoints, a human-readable message).
        error_message:
          type: string
          description: >-
            Human-readable detail. Present on endpoints that return an error
            code in `error`.
      required:
        - error
      x-apidog-orders:
        - error
        - error_message
      x-apidog-folder: ''
      x-apidog-ignore-properties: []
    GatewayError:
      type: object
      description: >-
        Returned by the API gateway itself when the bearer token is missing,
        invalid, expired or revoked, or the calling IP is not on the API key's
        allowlist.
      properties:
        message:
          type: string
          enum:
            - Forbidden
            - Unauthorized
      required:
        - message
      x-apidog-orders:
        - message
      x-apidog-folder: ''
      x-apidog-ignore-properties: []
  securitySchemes:
    bearerAuth:
      type: bearer
      scheme: bearer
      description: >-
        API key issued to the account holder, sent as `Authorization: Bearer
        <token>`. The key must hold the `SUBACCOUNT_TRANSFER` scope.
    bearer:
      type: http
      scheme: bearer
servers:
  - url: https://api.onetrading.com/fast
    description: Production Env
security: []

```