private/close_position

Places a reduce-only order to close an existing position. Reduce-only orders can only reduce or close a position; they cannot open a new position or increase an existing one.

You can specify whether to use a market or limit order. If using a limit order, provide the price. The order will automatically be set to reduce-only to ensure it only closes the position.

Scope: trade:read_write

Try in API console

cURL

cURL

curl --request GET \
  --url https://test.deribit.com/api/v2/private/close_position \
  --header 'Content-Type: application/json' \
  --data '
{
  "jsonrpc": "2.0",
  "id": 6130,
  "method": "private/close_position",
  "params": {
    "instrument_name": "ETH-PERPETUAL",
    "type": "limit",
    "price": 145.17
  }
}
'

200

{
  "jsonrpc": "2.0",
  "id": 6130,
  "result": {
    "trades": [
      {
        "trade_seq": 1966068,
        "trade_id": "ETH-2696097",
        "timestamp": 1590486335742,
        "tick_direction": 0,
        "state": "filled",
        "reduce_only": true,
        "price": 202.8,
        "post_only": false,
        "order_type": "limit",
        "order_id": "ETH-584864807",
        "matching_id": null,
        "mark_price": 202.79,
        "liquidity": "T",
        "instrument_name": "ETH-PERPETUAL",
        "index_price": 202.86,
        "fee_currency": "ETH",
        "fee": 0.00007766,
        "direction": "sell",
        "amount": 21
      }
    ],
    "order": {
      "web": false,
      "time_in_force": "good_til_cancelled",
      "replaced": false,
      "reduce_only": true,
      "price": 198.75,
      "post_only": false,
      "order_type": "limit",
      "order_state": "filled",
      "order_id": "ETH-584864807",
      "max_show": 21,
      "last_update_timestamp": 1590486335742,
      "label": "",
      "is_rebalance": false,
      "is_liquidation": false,
      "instrument_name": "ETH-PERPETUAL",
      "filled_amount": 21,
      "direction": "sell",
      "creation_timestamp": 1590486335742,
      "average_price": 202.8,
      "api": true,
      "amount": 21
    }
  }
}

Query Parameters

instrument_name · string · required

Instrument name Unique instrument identifier

Example:

"BTC-PERPETUAL"

type · enum<string> · required

The order type

Available options: limit, market

price · number

Optional price for limit order.

Response

200 - application/json

Success response

jsonrpc · enum<string> · required

The JSON-RPC version (2.0)

Available options: 2.0

result · object · required

Regular, trigger and OTO/OTOCO results contain order and trades. When a one_cancels_other request places two orders, the result contains oco_orders and trades instead. A single regular-order result still uses order.

Hide child attributes

result. trades · object[] · required

Hide child attributes

result.trades. trade_id · string · required

Unique (per currency) trade identifier

result.trades. trade_seq · integer · required

The sequence number of the trade within instrument

result.trades. instrument_name · string · required

Unique instrument identifier

Example:

"BTC-PERPETUAL"

result.trades. timestamp · integer · required

The timestamp of the trade (milliseconds since the UNIX epoch)

Example:

1517329113791

result.trades. order_id · string | null · required

Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade

result.trades. matching_id · string | null · required

Matched order id for self-trades; null otherwise.

result.trades. direction · enum<string> · required

Trade direction of the user

Available options: buy, sell

result.trades. tick_direction · enum<integer> · required

Direction of the "tick" (0 = Plus Tick, 1 = Zero-Plus Tick, 2 = Minus Tick, 3 = Zero-Minus Tick).

Available options: 0, 1, 2, 3

result.trades. index_price · number · required

Index Price at the moment of trade

result.trades. price · number · required

The price of the trade

result.trades. amount · number · required

Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.

result.trades. fee · number · required

User's fee in units of the specified fee_currency

result.trades. fee_currency · enum<string> · required

Currency, i.e "BTC", "ETH", "USDC"

Available options: BTC, ETH, USDC, USDT, EURR

result.trades. state · enum<string> · required

Order state: "open", "filled", "rejected", "cancelled", "untriggered" or "archive" (if order was archived)

Available options: open, filled, rejected, cancelled, untriggered, archive

result.trades. mark_price · number | null · required

Mark Price at the moment of trade

result.trades. starbase_timestamp · integer

Optional field: the Starbase causal timestamp of the trade, in nanoseconds since the UNIX epoch (present only for trades matched in Starbase)

Example:

1536569522277000000

result.trades. starbase_order_id · integer

Raw Starbase order id of the user's order, in Starbase's own (non currency-prefixed) id namespace (present only for trades matched in Starbase)

Example:

103148386170

result.trades. starbase_client_order_id · string

Client order id of the user's own order (maker or taker side) submitted directly to Starbase via direct access; not returned for orders placed through the Deribit API; for self-trades this is the taker order's client order id

result.trades. order_type · enum<string>

Order type: "limit", "market", or "liquidation"

Available options: limit, market, liquidation

result.trades. original_order_type · enum<string>

Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use "limit" as order_type with "market" in this optional field.

Available options: market, market_limit

result.trades. advanced · enum<string>

Advanced type of user order: "usd" or "implv" (only for options; omitted if not applicable)

Available options: usd, implv

result.trades. contracts · number

Trade size in contract units (optional, may be absent in historical trades)

result.trades. iv · number

Option implied volatility for the price (Option only)

result.trades. underlying_price · number

Underlying price for implied volatility calculations (Options only)

result.trades. liquidation · enum<string>

Optional field (only for trades caused by liquidation): "M" when maker side of trade was under liquidation, "T" when taker side was under liquidation, "MT" when both sides of trade were under liquidation

Available options: M, T, MT

result.trades. liquidity · enum<string>

Describes what was role of users order: "M" when it was maker order, "T" when it was taker order

Available options: M, T

result.trades. label · string

User defined label (presented only when previously set for order by user)

result.trades. block_trade_id · string

Block trade id - when trade was part of a block trade

Example:

"154"

result.trades. block_trade_leg_count · integer

Block trade leg count - when trade was part of a block trade

Example:

3

result.trades. block_rfq_id · integer

ID of the Block RFQ - when trade was part of the Block RFQ

result.trades. block_rfq_quote_id · integer

ID of the Block RFQ quote - when trade was part of the Block RFQ

result.trades. reduce_only · boolean

true if user order is reduce-only; omitted for spot trades.

result.trades. post_only · boolean

true if user order is post-only

result.trades. mmp · boolean

true if user order is MMP

result.trades. risk_reducing · boolean

true if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)

result.trades. api · boolean

true if user order was created with API

result.trades. profit_loss · number

Profit and loss in base currency.

result.trades. legs · array

Optional field containing leg trades if trade is a combo trade (present when querying for only combo trades and in combo_trades events). Each leg trade has the same fields as a top-level user trade, including starbase_match_id, starbase_order_id, and starbase_timestamp when matched in Starbase, and starbase_client_order_id for orders submitted via Starbase direct access.

result.trades. combo_id · string

Optional field containing combo instrument name if the trade is a combo trade

result.trades. combo_trade_id · string

Optional field containing combo trade identifier if the trade is a combo trade

result.trades. starbase_match_id · integer

Optional field containing the Starbase match identifier (present only for trades matched via Starbase)

result.trades. quote_set_id · string

QuoteSet of the user order (optional, present only for orders placed with private/mass_quote)

result.trades. quote_id · string

QuoteID of the user order (optional, present only for orders placed with private/mass_quote)

result.trades. trade_allocations · object[]

List of allocations for Block RFQ pre-allocation. Each allocation specifies user_id, amount, and fee for the allocated part of the trade. For broker client allocations, a client_info object will be included.

Hide child attributes

result.trades.trade_allocations. amount · number · required

Amount allocated to this user.

result.trades.trade_allocations. fee · number · required

Fee for the allocated part of the trade.

result.trades.trade_allocations. user_id · integer

User ID to which part of the trade is allocated. For brokers the User ID is obstructed.

result.trades.trade_allocations. client_info · object

Optional client allocation info for brokers.

Hide child attributes

result.trades.trade_allocations.client_info. client_id · integer

ID of a client; available to broker. Represents a group of users under a common name.

result.trades.trade_allocations.client_info. client_link_id · integer

ID assigned to a single user in a client; available to broker.

result.trades.trade_allocations.client_info. name · string

Name of the linked user within the client; available to broker.

result. order · object

Hide child attributes

result.order. order_id · string · required

Unique order identifier

Example:

"ETH-100234"

result.order. order_state · enum<string> · required

Order state: "open", "filled", "rejected", "cancelled", "untriggered"

Available options: open, filled, rejected, cancelled, untriggered, triggered

result.order. order_type · enum<string> · required

Order type: "limit", "market", "stop_limit", "stop_market", "take_limit", "take_market", "trailing_stop"

Available options: market, limit, stop_market, stop_limit, take_market, take_limit, trailing_stop

result.order. time_in_force · enum<string> · required

Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"

Available options: good_til_cancelled, good_til_day, fill_or_kill, immediate_or_cancel

result.order. instrument_name · string · required

Unique instrument identifier

Example:

"BTC-PERPETUAL"

result.order. creation_timestamp · integer · required

The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

result.order. last_update_timestamp · integer · required

The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

result.order. direction · enum<string> · required

Direction: buy, or sell

Available options: buy, sell

result.order. price · number enum<string> · required

Price in the instrument's price units (quote currency for futures and spot), or market_price for open trigger market orders.

result.order. label · string · required

User defined label (up to 64 characters)

result.order. post_only · boolean · required

true for post-only orders only

result.order. api · boolean · required

true if created with API

result.order. original_order_type · enum<string>

Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use "limit" as order_type with "market" in this optional field.

Available options: market, market_limit

result.order. is_rebalance · boolean

Optional (only for spot). true if order was automatically created during cross-collateral balance restoration

result.order. is_liquidation · boolean

Optional (not added for spot). true if order was automatically created during liquidation

result.order. starbase_last_update_timestamp · integer

The Starbase causal timestamp (nanoseconds since the Unix epoch) of the last book update that affected this order. Present only for orders placed in Starbase, including combo leg order updates; not always available for direct access orders

Example:

1536569522277000000

result.order. starbase_client_order_id · string

Client order id of an order submitted directly to Starbase via direct access; not returned for orders placed through the Deribit API (combo legs inherit the parent combo order's client order id)

result.order. reject_post_only · boolean

true if order has reject_post_only flag (field is present only when post_only is true)

result.order. reduce_only · boolean

Optional (not added for spot). 'true for reduce-only orders only'

result.order. web · boolean

true if created via Deribit frontend (optional)

result.order. mobile · boolean

Optional field with value true added only when created with Mobile Application

result.order. refresh_amount · number

The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders

result.order. display_amount · number

The actual display amount of iceberg order. Absent for other types of orders.

result.order. amount · number

It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.

result.order. contracts · number

It represents the order size in contract units. (Optional, may be absent in historical data).

result.order. filled_amount · number

Filled amount of the order. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.

result.order. average_price · number

Average fill price of the order

result.order. advanced · enum<string>

advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).

Available options: usd, implv

result.order. implv · number

Implied volatility in percent. (Only if advanced="implv")

result.order. usd · number

Option price in USD (Only if advanced="usd")

result.order. triggered · boolean

Whether the trigger order has been triggered

result.order. trigger · enum<string>

Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".

Available options: index_price, mark_price, last_price

result.order. trigger_price · number

Trigger price (Only for future trigger orders)

result.order. trigger_offset · number

The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)

result.order. trigger_reference_price · number

The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)

result.order. block_trade · boolean

true if order made from block_trade trade, added only in that case.

Example:

true

result.order. mmp · boolean

true if the order is a MMP order, otherwise false.

result.order. risk_reducing · boolean

true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.

result.order. replaced · boolean

true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.

result.order. auto_replaced · boolean

Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.

result.order. quote · boolean

If order is a quote. Present only if true.

result.order. mmp_group · string

Name of the MMP group supplied in the private/mass_quote request. Only present for quote orders.

result.order. quote_set_id · string

Identifier of the QuoteSet supplied in the private/mass_quote request. Only present for quote orders.

result.order. quote_id · string

The same QuoteID as supplied in the private/mass_quote request. Only present for quote orders.

result.order. trigger_order_id · string

Id of the trigger order that created the order (Only for orders that were created by triggered orders).

Example:

"SLIB-370"

result.order. combo_order_id · string

Id of the combo order that created this order (only present for orders that were created as legs of a combo order).

Example:

"103148386169"

result.order. starbase_order_id · integer

Raw Starbase order id, in Starbase's own (non currency-prefixed) id namespace. Only present for orders placed in Starbase. Combo leg orders expose the parent combo order's Starbase order id.

Example:

103148386170

result.order. app_name · string

The name of the application that placed the order on behalf of the user (optional).

Example:

"Example Application"

result.order. mmp_cancelled · boolean

true if order was cancelled by mmp trigger (optional)

Example:

true

result.order. cancel_reason · enum<string>

Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement event, e.g. good-til-day orders are cancelled when an instrument enters the daily settlement). Note: orders cancelled because an instrument expired (delivery) currently do not include a cancel_reason field.

Available options: user_request, autoliquidation, cancel_on_disconnect, risk_mitigation, pme_risk_reduction, pme_account_locked, position_locked, mmp_trigger, mmp_config_curtailment, edit_post_only_reject, oco_other_closed, oto_primary_closed, settlement

result.order. oto_order_ids · string[]

The Ids of the orders that will be triggered if the order is filled

Order Id

result.order. trigger_fill_condition · enum<string>

The fill condition of the linked order (Only for linked order types), default: `first_hit`.

• `"first_hit"` - any execution of the primary order will fully cancel/place all secondary orders.
• `"complete_fill"` - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
• `"incremental"` - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.

Available options: first_hit, complete_fill, incremental

result.order. oco_ref · string

Unique reference that identifies a one_cancels_others (OCO) pair.

result.order. primary_order_id · string

ID of the order that triggered this order.

Example:

"ETH-100234"

result.order. is_secondary_oto · boolean

true if the order is an order that can be triggered by another order, otherwise not present.

result.order. is_primary_otoco · boolean

true if the order is an order that can trigger an OCO pair, otherwise not present.

result. oco_orders · object[]

The two orders placed by an OCO request; returned instead of order.

Hide child attributes

result.oco_orders. order_id · string · required

Unique order identifier

Example:

"ETH-100234"

result.oco_orders. order_state · enum<string> · required

Order state: "open", "filled", "rejected", "cancelled", "untriggered"

Available options: open, filled, rejected, cancelled, untriggered, triggered

result.oco_orders. order_type · enum<string> · required

Order type: "limit", "market", "stop_limit", "stop_market", "take_limit", "take_market", "trailing_stop"

Available options: market, limit, stop_market, stop_limit, take_market, take_limit, trailing_stop

result.oco_orders. time_in_force · enum<string> · required

Order time in force: "good_til_cancelled", "good_til_day", "fill_or_kill" or "immediate_or_cancel"

Available options: good_til_cancelled, good_til_day, fill_or_kill, immediate_or_cancel

result.oco_orders. instrument_name · string · required

Unique instrument identifier

Example:

"BTC-PERPETUAL"

result.oco_orders. creation_timestamp · integer · required

The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

result.oco_orders. last_update_timestamp · integer · required

The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

result.oco_orders. direction · enum<string> · required

Direction: buy, or sell

Available options: buy, sell

result.oco_orders. price · number enum<string> · required

Price in the instrument's price units (quote currency for futures and spot), or market_price for open trigger market orders.

result.oco_orders. label · string · required

User defined label (up to 64 characters)

result.oco_orders. post_only · boolean · required

true for post-only orders only

result.oco_orders. api · boolean · required

true if created with API

result.oco_orders. original_order_type · enum<string>

Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use "limit" as order_type with "market" in this optional field.

Available options: market, market_limit

result.oco_orders. is_rebalance · boolean

Optional (only for spot). true if order was automatically created during cross-collateral balance restoration

result.oco_orders. is_liquidation · boolean

Optional (not added for spot). true if order was automatically created during liquidation

result.oco_orders. starbase_last_update_timestamp · integer

The Starbase causal timestamp (nanoseconds since the Unix epoch) of the last book update that affected this order. Present only for orders placed in Starbase, including combo leg order updates; not always available for direct access orders

Example:

1536569522277000000

result.oco_orders. starbase_client_order_id · string

Client order id of an order submitted directly to Starbase via direct access; not returned for orders placed through the Deribit API (combo legs inherit the parent combo order's client order id)

result.oco_orders. reject_post_only · boolean

true if order has reject_post_only flag (field is present only when post_only is true)

result.oco_orders. reduce_only · boolean

Optional (not added for spot). 'true for reduce-only orders only'

result.oco_orders. web · boolean

true if created via Deribit frontend (optional)

result.oco_orders. mobile · boolean

Optional field with value true added only when created with Mobile Application

result.oco_orders. refresh_amount · number

The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders

result.oco_orders. display_amount · number

The actual display amount of iceberg order. Absent for other types of orders.

result.oco_orders. amount · number

It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.

result.oco_orders. contracts · number

It represents the order size in contract units. (Optional, may be absent in historical data).

result.oco_orders. filled_amount · number

Filled amount of the order. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.

result.oco_orders. average_price · number

Average fill price of the order

result.oco_orders. advanced · enum<string>

advanced type: "usd" or "implv" (Only for options; field is omitted if not applicable).

Available options: usd, implv

result.oco_orders. implv · number

Implied volatility in percent. (Only if advanced="implv")

result.oco_orders. usd · number

Option price in USD (Only if advanced="usd")

result.oco_orders. triggered · boolean

Whether the trigger order has been triggered

result.oco_orders. trigger · enum<string>

Trigger type (only for trigger orders). Allowed values: "index_price", "mark_price", "last_price".

Available options: index_price, mark_price, last_price

result.oco_orders. trigger_price · number

Trigger price (Only for future trigger orders)

result.oco_orders. trigger_offset · number

The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)

result.oco_orders. trigger_reference_price · number

The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)

result.oco_orders. block_trade · boolean

true if order made from block_trade trade, added only in that case.

Example:

true

result.oco_orders. mmp · boolean

true if the order is a MMP order, otherwise false.

result.oco_orders. risk_reducing · boolean

true if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise false.

result.oco_orders. replaced · boolean

true if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise false.

result.oco_orders. auto_replaced · boolean

Options, advanced orders only - true if last modification of the order was performed by the pricing engine, otherwise false.

result.oco_orders. quote · boolean

If order is a quote. Present only if true.

result.oco_orders. mmp_group · string

Name of the MMP group supplied in the private/mass_quote request. Only present for quote orders.

result.oco_orders. quote_set_id · string

Identifier of the QuoteSet supplied in the private/mass_quote request. Only present for quote orders.

result.oco_orders. quote_id · string

The same QuoteID as supplied in the private/mass_quote request. Only present for quote orders.

result.oco_orders. trigger_order_id · string

Id of the trigger order that created the order (Only for orders that were created by triggered orders).

Example:

"SLIB-370"

result.oco_orders. combo_order_id · string

Id of the combo order that created this order (only present for orders that were created as legs of a combo order).

Example:

"103148386169"

result.oco_orders. starbase_order_id · integer

Raw Starbase order id, in Starbase's own (non currency-prefixed) id namespace. Only present for orders placed in Starbase. Combo leg orders expose the parent combo order's Starbase order id.

Example:

103148386170

result.oco_orders. app_name · string

The name of the application that placed the order on behalf of the user (optional).

Example:

"Example Application"

result.oco_orders. mmp_cancelled · boolean

true if order was cancelled by mmp trigger (optional)

Example:

true

result.oco_orders. cancel_reason · enum<string>

Enumerated reason behind cancel "user_request", "autoliquidation", "cancel_on_disconnect", "risk_mitigation", "pme_risk_reduction" (portfolio margining risk reduction), "pme_account_locked" (portfolio margining account locked per currency), "position_locked", "mmp_trigger" (market maker protection), "mmp_config_curtailment" (market maker configured quantity decreased), "edit_post_only_reject" (cancelled on edit because of reject_post_only setting), "oco_other_closed" (the oco order linked to this order was closed), "oto_primary_closed" (the oto primary order that was going to trigger this order was cancelled), "settlement" (closed because of a settlement event, e.g. good-til-day orders are cancelled when an instrument enters the daily settlement). Note: orders cancelled because an instrument expired (delivery) currently do not include a cancel_reason field.

Available options: user_request, autoliquidation, cancel_on_disconnect, risk_mitigation, pme_risk_reduction, pme_account_locked, position_locked, mmp_trigger, mmp_config_curtailment, edit_post_only_reject, oco_other_closed, oto_primary_closed, settlement

result.oco_orders. oto_order_ids · string[]

The Ids of the orders that will be triggered if the order is filled

Order Id

result.oco_orders. trigger_fill_condition · enum<string>

The fill condition of the linked order (Only for linked order types), default: `first_hit`.

• `"first_hit"` - any execution of the primary order will fully cancel/place all secondary orders.
• `"complete_fill"` - a complete execution (meaning the primary order no longer exists) will cancel/place the secondary orders.
• `"incremental"` - any fill of the primary order will cause proportional partial cancellation/placement of the secondary order. The amount that will be subtracted/added to the secondary order will be rounded down to the contract size.

Available options: first_hit, complete_fill, incremental

result.oco_orders. oco_ref · string

Unique reference that identifies a one_cancels_others (OCO) pair.

result.oco_orders. primary_order_id · string

ID of the order that triggered this order.

Example:

"ETH-100234"

result.oco_orders. is_secondary_oto · boolean

true if the order is an order that can be triggered by another order, otherwise not present.

result.oco_orders. is_primary_otoco · boolean

true if the order is an order that can trigger an OCO pair, otherwise not present.

id · integer

The id that was sent in the request