REST reference / Trading and account

Income history

GET/fapi/v1/income

Signed requestRead permissionWeight 30

Overview

Persisted wallet movements, oldest first, may lag live balance

Send X-MBX-APIKEY and an HMAC-SHA256 signature. Sign requests in your own client. Authentication guide

Behavior and request rules

Requires X-MBX-APIKEY and per-request HMAC-SHA256. Send timestamp (milliseconds), optional recvWindow (default 5000, maximum 60000), and signature. Sign the exact raw query followed by the exact raw body, with NO inserted ampersand, excluding signature. Signature must be last in query or body. Query values take precedence over body values; the first duplicate in each location wins. Values are not percent-decoded. Timestamp must be less than serverTime + 1000 and serverTime - timestamp <= recvWindow. The API-key authorization field alone does not sign requests.

Parameters may be in query, raw urlencoded body, or split across both. Required fields apply to the merged parameters, not independently to each location. Query parameters are marked optional to represent this alternative. GET bodies work at the server but many HTTP clients and proxies cannot send them; use query parameters for portable GET requests. Send the exact bytes you signed, without form re-encoding.

USER_DATA (READ) permission is required.

Parameters

Required fields apply across query and form body. Query values take precedence. The examples use query parameters only.

symbolstringoptional

Listed symbol, for example BTCUSDT. Unlisted symbols return -1121.

Constraints

type: "string"

startTimeintegeroptional

Inclusive epoch milliseconds; absent means unbounded.

Constraints

type: "integer"
format: "int64"

endTimeintegeroptional

Inclusive epoch milliseconds; absent means unbounded.

Constraints

type: "integer"
format: "int64"

limitintegeroptional

Values above 1000 are clamped to 1000.

Constraints

type: "integer"
minimum: 1
default: 100

incomeTypestringoptional

TRANSFER, REALIZED_PNL, COMMISSION, FUNDING_FEE; other types return an empty array.

Constraints

type: "string"

pageintegeroptional

One-based page number.

Constraints

type: "integer"
minimum: 1
default: 1

timestampintegerrequired

Client epoch milliseconds checked against the receive window.

Constraints

type: "integer"
format: "int64"

recvWindowintegeroptional

Receive window in milliseconds.

Constraints

type: "integer"
minimum: 1
maximum: 60000
default: 5000

signaturestringrequired

HMAC-SHA256 of exact raw query + body excluding signature; final parameter in query or body.

Constraints

type: "string"
pattern: "^[0-9a-fA-F]{64}$"

Conditional and combined requirements

These constraints apply after query and body parameters are combined. Field descriptions above explain conditions such as the LIMIT price requirement.

{
  "properties": {
    "endTime": {
      "description": "Inclusive epoch milliseconds; absent means unbounded.",
      "format": "int64",
      "type": "integer"
    },
    "incomeType": {
      "description": "TRANSFER, REALIZED_PNL, COMMISSION, FUNDING_FEE; other types return an empty array.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Values above 1000 are clamped to 1000.",
      "minimum": 1,
      "type": "integer"
    },
    "page": {
      "default": 1,
      "description": "One-based page number.",
      "minimum": 1,
      "type": "integer"
    },
    "recvWindow": {
      "default": 5000,
      "description": "Receive window in milliseconds.",
      "maximum": 60000,
      "minimum": 1,
      "type": "integer"
    },
    "signature": {
      "description": "HMAC-SHA256 of exact raw query + body excluding signature; final parameter in query or body.",
      "pattern": "^[0-9a-fA-F]{64}$",
      "type": "string"
    },
    "startTime": {
      "description": "Inclusive epoch milliseconds; absent means unbounded.",
      "format": "int64",
      "type": "integer"
    },
    "symbol": {
      "description": "Listed symbol, for example BTCUSDT. Unlisted symbols return -1121.",
      "type": "string"
    },
    "timestamp": {
      "description": "Client epoch milliseconds checked against the receive window.",
      "format": "int64",
      "type": "integer"
    }
  },
  "required": [
    "timestamp",
    "signature"
  ],
  "type": "object"
}

Form body schema

{
  "application/x-www-form-urlencoded": {
    "schema": {
      "properties": {
        "endTime": {
          "description": "Inclusive epoch milliseconds; absent means unbounded.",
          "format": "int64",
          "type": "integer"
        },
        "incomeType": {
          "description": "TRANSFER, REALIZED_PNL, COMMISSION, FUNDING_FEE; other types return an empty array.",
          "type": "string"
        },
        "limit": {
          "default": 100,
          "description": "Values above 1000 are clamped to 1000.",
          "minimum": 1,
          "type": "integer"
        },
        "page": {
          "default": 1,
          "description": "One-based page number.",
          "minimum": 1,
          "type": "integer"
        },
        "recvWindow": {
          "default": 5000,
          "description": "Receive window in milliseconds.",
          "maximum": 60000,
          "minimum": 1,
          "type": "integer"
        },
        "signature": {
          "description": "HMAC-SHA256 of exact raw query + body excluding signature; final parameter in query or body.",
          "pattern": "^[0-9a-fA-F]{64}$",
          "type": "string"
        },
        "startTime": {
          "description": "Inclusive epoch milliseconds; absent means unbounded.",
          "format": "int64",
          "type": "integer"
        },
        "symbol": {
          "description": "Listed symbol, for example BTCUSDT. Unlisted symbols return -1121.",
          "type": "string"
        },
        "timestamp": {
          "description": "Client epoch milliseconds checked against the receive window.",
          "format": "int64",
          "type": "integer"
        }
      },
      "type": "object"
    }
  }
}

Responses

Success

Array items Income

assetstringrequired

type: "string"

incomestringrequired

Decimal encoded as a string. Precision follows the symbol or the field's documented scale. Never convert to a binary floating-point number for signing or accounting.

type: "string"
pattern: "^-?[0-9]+(\\.[0-9]+)?$"

incomeTypestringrequired

type: "string"

infostringrequired

type: "string"

symbolstringrequired

type: "string"

timeintegerrequired

type: "integer"
format: "int64"

tradeIdstringrequired

type: "string"

tranIdintegerrequired

type: "integer"
format: "int64"

type: "object"
additionalProperties: false

type: "array"

Response headers

X-DP-ACCOUNT-USED-WEIGHT-1M

Per-verified-Trading-Account admitted weight when authenticated.

X-MBX-USED-WEIGHT-1M

Per-IP admitted request weight in the current minute. Requests admitted by the limiter count even if authentication or validation later fails.

Raw response schema

{
  "$ref": "#/components/schemas/Incomes"
}

Errors, limits and retry behavior