REST reference / Trading and account

Place an order

POST/fapi/v1/order

Signed requestTrading permissionWeight 1

Overview

Place LIMIT or MARKET order

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.

TRADE permission is required.

closePosition, stopPrice, priceMatch, goodTillDate and workingType are rejected when present. MARKET rejects price when present, and MARKET timeInForce accepts absent or IOC only. LIMIT timeInForce defaults to GTC. STP defaults to EXPIRE_MAKER and NONE is rejected. After an uncertain command outcome, query authoritative order/open-order state before retrying; persisted history may lag.

Parameters

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

symbolstringrequired

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

Constraints

type: "string"

sidestringrequired

Order side.

Constraints

type: "string"
enum: ["BUY","SELL"]

typestringrequired

Only LIMIT and MARKET are implemented.

Constraints

type: "string"
enum: ["LIMIT","MARKET"]

quantitystringrequired

Positive quantity at symbol precision and within symbol filters.

Constraints

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]+)?$"

pricestringoptional

Required for LIMIT. Rejected when present for MARKET.

Constraints

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]+)?$"

timeInForcestringoptional

LIMIT defaults to GTC. MARKET accepts absent or IOC only.

Constraints

type: "string"
enum: ["GTC","IOC","FOK","GTX"]

reduceOnlystringoptional

Default false.

Constraints

type: "string"
enum: ["false","true"]

positionSidestringoptional

Only BOTH is accepted.

Constraints

type: "string"
enum: ["BOTH"]

newClientOrderIdstringoptional

Unique among open orders. Duplicate open IDs return -4116. Resolve uncertain outcomes through reads before retrying.

Constraints

type: "string"
pattern: "^[.A-Z:/a-z0-9_-]{1,36}$"

newOrderRespTypestringoptional

Both return the same synchronous post-match report.

Constraints

type: "string"
enum: ["ACK","RESULT"]

selfTradePreventionModestringoptional

Default EXPIRE_MAKER. NONE is rejected; applied by the matching engine.

Constraints

type: "string"
enum: ["EXPIRE_TAKER","EXPIRE_MAKER","EXPIRE_BOTH"]

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.

{
  "allOf": [
    {
      "if": {
        "properties": {
          "type": {
            "const": "LIMIT"
          }
        }
      },
      "then": {
        "required": [
          "price"
        ]
      }
    },
    {
      "if": {
        "properties": {
          "type": {
            "const": "MARKET"
          }
        }
      },
      "then": {
        "not": {
          "required": [
            "price"
          ]
        },
        "properties": {
          "timeInForce": {
            "const": "IOC"
          }
        }
      }
    },
    {
      "not": {
        "anyOf": [
          {
            "required": [
              "closePosition"
            ]
          },
          {
            "required": [
              "stopPrice"
            ]
          },
          {
            "required": [
              "priceMatch"
            ]
          },
          {
            "required": [
              "goodTillDate"
            ]
          },
          {
            "required": [
              "workingType"
            ]
          }
        ]
      }
    }
  ],
  "properties": {
    "newClientOrderId": {
      "description": "Unique among open orders. Duplicate open IDs return -4116. Resolve uncertain outcomes through reads before retrying.",
      "pattern": "^[.A-Z:/a-z0-9_-]{1,36}$",
      "type": "string"
    },
    "newOrderRespType": {
      "description": "Both return the same synchronous post-match report.",
      "enum": [
        "ACK",
        "RESULT"
      ],
      "type": "string"
    },
    "positionSide": {
      "description": "Only BOTH is accepted.",
      "enum": [
        "BOTH"
      ],
      "type": "string"
    },
    "price": {
      "description": "Required for LIMIT. Rejected when present for MARKET.",
      "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
      "type": "string"
    },
    "quantity": {
      "description": "Positive quantity at symbol precision and within symbol filters.",
      "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
      "type": "string"
    },
    "recvWindow": {
      "default": 5000,
      "description": "Receive window in milliseconds.",
      "maximum": 60000,
      "minimum": 1,
      "type": "integer"
    },
    "reduceOnly": {
      "description": "Default false.",
      "enum": [
        "false",
        "true"
      ],
      "type": "string"
    },
    "selfTradePreventionMode": {
      "description": "Default EXPIRE_MAKER. NONE is rejected; applied by the matching engine.",
      "enum": [
        "EXPIRE_TAKER",
        "EXPIRE_MAKER",
        "EXPIRE_BOTH"
      ],
      "type": "string"
    },
    "side": {
      "description": "Order side.",
      "enum": [
        "BUY",
        "SELL"
      ],
      "type": "string"
    },
    "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"
    },
    "symbol": {
      "description": "Listed symbol, for example BTCUSDT. Unlisted symbols return -1121.",
      "type": "string"
    },
    "timeInForce": {
      "description": "LIMIT defaults to GTC. MARKET accepts absent or IOC only.",
      "enum": [
        "GTC",
        "IOC",
        "FOK",
        "GTX"
      ],
      "type": "string"
    },
    "timestamp": {
      "description": "Client epoch milliseconds checked against the receive window.",
      "format": "int64",
      "type": "integer"
    },
    "type": {
      "description": "Only LIMIT and MARKET are implemented.",
      "enum": [
        "LIMIT",
        "MARKET"
      ],
      "type": "string"
    }
  },
  "required": [
    "symbol",
    "side",
    "type",
    "quantity",
    "timestamp",
    "signature"
  ],
  "type": "object"
}

Form body schema

{
  "application/x-www-form-urlencoded": {
    "schema": {
      "properties": {
        "newClientOrderId": {
          "description": "Unique among open orders. Duplicate open IDs return -4116. Resolve uncertain outcomes through reads before retrying.",
          "pattern": "^[.A-Z:/a-z0-9_-]{1,36}$",
          "type": "string"
        },
        "newOrderRespType": {
          "description": "Both return the same synchronous post-match report.",
          "enum": [
            "ACK",
            "RESULT"
          ],
          "type": "string"
        },
        "positionSide": {
          "description": "Only BOTH is accepted.",
          "enum": [
            "BOTH"
          ],
          "type": "string"
        },
        "price": {
          "description": "Required for LIMIT. Rejected when present for MARKET.",
          "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
          "type": "string"
        },
        "quantity": {
          "description": "Positive quantity at symbol precision and within symbol filters.",
          "pattern": "^-?[0-9]+(\\.[0-9]+)?$",
          "type": "string"
        },
        "recvWindow": {
          "default": 5000,
          "description": "Receive window in milliseconds.",
          "maximum": 60000,
          "minimum": 1,
          "type": "integer"
        },
        "reduceOnly": {
          "description": "Default false.",
          "enum": [
            "false",
            "true"
          ],
          "type": "string"
        },
        "selfTradePreventionMode": {
          "description": "Default EXPIRE_MAKER. NONE is rejected; applied by the matching engine.",
          "enum": [
            "EXPIRE_TAKER",
            "EXPIRE_MAKER",
            "EXPIRE_BOTH"
          ],
          "type": "string"
        },
        "side": {
          "description": "Order side.",
          "enum": [
            "BUY",
            "SELL"
          ],
          "type": "string"
        },
        "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"
        },
        "symbol": {
          "description": "Listed symbol, for example BTCUSDT. Unlisted symbols return -1121.",
          "type": "string"
        },
        "timeInForce": {
          "description": "LIMIT defaults to GTC. MARKET accepts absent or IOC only.",
          "enum": [
            "GTC",
            "IOC",
            "FOK",
            "GTX"
          ],
          "type": "string"
        },
        "timestamp": {
          "description": "Client epoch milliseconds checked against the receive window.",
          "format": "int64",
          "type": "integer"
        },
        "type": {
          "description": "Only LIMIT and MARKET are implemented.",
          "enum": [
            "LIMIT",
            "MARKET"
          ],
          "type": "string"
        }
      },
      "type": "object"
    }
  }
}

Responses

Success

avgPricestringrequired

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]+)?$"

clientOrderIdstringrequired

type: "string"

closePositionbooleanrequired

type: "boolean"

cumQtystringrequired

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]+)?$"

cumQuotestringrequired

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]+)?$"

executedQtystringrequired

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]+)?$"

goodTillDateintegerrequired

type: "integer"
format: "int64"

orderIdintegerrequired

type: "integer"
format: "int64"

origQtystringrequired

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]+)?$"

origTypestringrequired

type: "string"
enum: ["LIMIT","MARKET"]

positionSidestringrequired

type: "string"
enum: ["BOTH"]

pricestringrequired

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]+)?$"

priceMatchstringrequired

type: "string"
enum: ["NONE"]

priceProtectbooleanrequired

type: "boolean"

reduceOnlybooleanrequired

type: "boolean"

selfTradePreventionModestringrequired

type: "string"
enum: ["NONE","EXPIRE_TAKER","EXPIRE_MAKER","EXPIRE_BOTH"]

sidestringrequired

type: "string"
enum: ["BUY","SELL"]

statusstringrequired

type: "string"
enum: ["NEW","PARTIALLY_FILLED","FILLED","CANCELED","EXPIRED","EXPIRED_IN_MATCH"]

stopPricestringrequired

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]+)?$"

symbolstringrequired

type: "string"

timeInForcestringrequired

type: "string"
enum: ["GTC","IOC","FOK","GTX"]

typestringrequired

type: "string"
enum: ["LIMIT","MARKET"]

updateTimeintegerrequired

type: "integer"
format: "int64"

workingTypestringrequired

type: "string"
enum: ["CONTRACT_PRICE"]

type: "object"
additionalProperties: false

Response headers

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

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

X-MBX-ORDER-COUNT-1M

Completed successful placements for the verified account. Outstanding reservations can exhaust capacity below this count. Absent for unauthenticated requests.

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

Errors, limits and retry behavior