# Change position margin

`PATCH /positions/{positionId}/margin`

Moves quote balance in or out of the margin of an open position, which moves its leverage and liquidation price with it.

- The position must still be open, and its account must belong to the caller and be `active` — an account locked by the managed capital limit is refused here.
- The market must be open and not in close-only mode.
- `marginChange: "0"` is accepted and returns the position untouched.
- Adding more than the free balance covers fails with `insufficient_balance`; withdrawing more than the position can spare fails with `non_positive_margin`.

## Authorization

bearer: http · bearer (required). Personal API key, prefixed with `usk_`.

## Parameters

- path: positionId (string · uuid; required). Position identifier. Its account must belong to the caller.

Type: string · uuid

format: uuid

## Request body · MarginChangeRequest

application/json · required

Schema: MarginChangeRequest

Type: object

Required fields: marginChange

Required field types: marginChange (string · int32; required)

- marginChange (string · int32; required)

marginChange example: 1000000000

marginChange.Type: string · int32

marginChange.Signed quote amount to move in or out of the position margin, fp9 raw. Positive adds margin and requires that much free balance, negative withdraws it and must keep the remaining margin positive. `0` is accepted and changes nothing.

marginChange.format: int32

marginChange.pattern: ^(?:-?[1-9][0-9]*|0)$

Example



```json
{
  "marginChange": "1000000000"
}
```

## Example · cURL

```bash
curl --request PATCH 'https://api.upscale.trade/positions/{positionId}/margin' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "marginChange": "1000000000"
}'
```

## Example · JavaScript

```javascript
const response = await fetch("https://api.upscale.trade/positions/{positionId}/margin", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: "{\n  \"marginChange\": \"1000000000\"\n}",
});
console.log(response.status, await response.text());
```

## Example · Python

```python
import requests

response = requests.request(
    "PATCH",
    "https://api.upscale.trade/positions/{positionId}/margin",
    headers={"Accept":"application/json","Authorization":"Bearer YOUR_API_KEY","Content-Type":"application/json"},
    data="{\n  \"marginChange\": \"1000000000\"\n}",
    timeout=30,
)
print(response.status_code, response.text)
```

## Response 401

**401**  — Unauthorized

## Response 403

**403**  — The account belongs to another user (`account_access_denied`), or the request is authenticated with an API key while `api_trading` is disabled on the account (`api_trading_not_enabled`). The account is not in an active status. The market is paused (`market_paused`) or accepts closing orders only (`market_close_only`).

## Response 404

**404**  — No position with this identifier.

## Response 429

**429**  — Rate limit of the API key exceeded (`api_key_rate_limit_exceeded`). `Retry-After` says when to come back; the body carries the bucket (`read` / `write`), the window that tripped, its limit and `retryAt`.

## Response default · PositionResponse

**default** application/json — Response

Schema: PositionResponse

Type: object

Required fields: idx, txId, version, openedAt, lastUpdatedAt, closedAt, type, status, market, trader, size, notional, fraction, margin, pnl, funding, rolloverFee, settlementOraclePrice, fee, feeRate, exchangedQuote, exchangedBase, direction, eventName, pnlInEvent, rawPnlInEvent, profitAdjustmentApplied, holdingTimeMs, feeInEvent, fundingInEvent, rolloverFeeInEvent, executionFeeRate, executionFeeInEvent, executionFee, timestamp, isOnchain, roe, scalpingCoefficient, closeReason

Required field types: idx (string[]; required), txId (string[]; required), version (number; required), openedAt (string · date-time; required), lastUpdatedAt (string · date-time; required), closedAt (string · date-time · nullable; required), type (string · enum; required), status (string · enum; required), market (string · uuid; required), trader (string · uuid; required), size (string · int32; required), notional (string · int32; required), fraction (string · int32; required), margin (string · int32; required), pnl (string · int32 · nullable; required), funding (string · int32 · nullable; required), rolloverFee (string · int32; required), settlementOraclePrice (string · int32; required), fee (string · int32; required), feeRate (string · int32; required), exchangedQuote (string · int32; required), exchangedBase (string · int32; required), direction (string · enum; required), eventName (string · enum; required), pnlInEvent (string · int32; required), rawPnlInEvent (string · int32; required), profitAdjustmentApplied (boolean; required), holdingTimeMs (string[]; required), feeInEvent (string · int32; required), fundingInEvent (string · int32; required), rolloverFeeInEvent (string · int32; required), executionFeeRate (string · int32; required), executionFeeInEvent (string · int32; required), executionFee (string · int32; required), timestamp (string · date-time; required), isOnchain (boolean; required), roe (string · int32; required), scalpingCoefficient (string · int32; required), closeReason (string[]; required)

- idx (string[]; required)

idx example: [
  "string"
]

idx.Type: string[]

idx.Position identifier. Same value as `txId`.

idx.[]Type: string

- txId (string[]; required)

txId example: [
  "string"
]

txId.Type: string[]

txId.Position identifier. Kept for backward compatibility, always equal to `idx`.

txId.[]Type: string

- version (number; required)

version example: 0

version.Type: number

version.Revision of the position: incremented by every event applied to it.

- openedAt (string · date-time; required)

openedAt example: 2026-05-01T12:30:00.000Z

openedAt.Type: string · date-time

openedAt.When the position was opened.

openedAt.format: date-time

- lastUpdatedAt (string · date-time; required)

lastUpdatedAt example: 2026-05-01T12:30:00.000Z

lastUpdatedAt.Type: string · date-time

lastUpdatedAt.When the last event was applied to the position.

lastUpdatedAt.format: date-time

- closedAt (string · date-time · nullable; required)

closedAt example: 2026-05-01T12:30:00.000Z

closedAt.Type: string · date-time · nullable

closedAt.When the position was closed; null while it is still open.

closedAt.format: date-time

- type (string · enum; required)

type example: long

type.Type: string · enum

type.Direction of the position. Same value as `direction`.

type.Allowed values: ["long","short"]

- status (string · enum; required)

status example: opened

status.Type: string · enum

status.Whether the position is still open, closed by the trader, or liquidated.

status.Allowed values: ["opened","closed","liquidated"]

- market (string · uuid; required)

market example: 00000000-0000-4000-8000-000000000000

market.Type: string · uuid

market.Market the position is held on.

market.format: uuid

market.pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

- trader (string · uuid; required)

trader example: 00000000-0000-4000-8000-000000000000

trader.Type: string · uuid

trader.Trader account the position belongs to.

trader.format: uuid

trader.pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

- size (string · int32; required)

size example: 1000000000

size.Type: string · int32

size.Position size in base asset units, fp9 raw.

size.format: int32

size.pattern: ^(?:-?[1-9][0-9]*|0)$

- notional (string · int32; required)

notional example: 1000000000

notional.Type: string · int32

notional.Open notional of the position in quote currency, fp9 raw — size at entry price.

notional.format: int32

notional.pattern: ^(?:-?[1-9][0-9]*|0)$

- fraction (string · int32; required)

fraction example: 1000000000

fraction.Type: string · int32

fraction.Always `0`. Kept for backward compatibility.

fraction.format: int32

fraction.pattern: ^(?:-?[1-9][0-9]*|0)$

- margin (string · int32; required)

margin example: 1000000000

margin.Type: string · int32

margin.Margin currently backing the position, fp9 raw. Moves with pnl, funding and manual margin changes.

margin.format: int32

margin.pattern: ^(?:-?[1-9][0-9]*|0)$

- pnl (string · int32 · nullable; required)

pnl example: 1000000000

pnl.Type: string · int32 · nullable

pnl.Realised pnl accumulated over every event of the position, fp9 raw.

pnl.format: int32

pnl.pattern: ^(?:-?[1-9][0-9]*|0)$

- funding (string · int32 · nullable; required)

funding example: 1000000000

funding.Type: string · int32 · nullable

funding.Funding paid (negative) or received (positive) over the life of the position, fp9 raw.

funding.format: int32

funding.pattern: ^(?:-?[1-9][0-9]*|0)$

- rolloverFee (string · int32; required)

rolloverFee example: 1000000000

rolloverFee.Type: string · int32

rolloverFee.Always `0`. Kept for backward compatibility.

rolloverFee.format: int32

rolloverFee.pattern: ^(?:-?[1-9][0-9]*|0)$

- settlementOraclePrice (string · int32; required)

settlementOraclePrice example: 1000000000

settlementOraclePrice.Type: string · int32

settlementOraclePrice.Always `1000000000` (1.0). Kept for backward compatibility.

settlementOraclePrice.format: int32

settlementOraclePrice.pattern: ^(?:-?[1-9][0-9]*|0)$

- fee (string · int32; required)

fee example: 1000000000

fee.Type: string · int32

fee.Trading fees charged over the life of the position, fp9 raw.

fee.format: int32

fee.pattern: ^(?:-?[1-9][0-9]*|0)$

- feeRate (string · int32; required)

feeRate example: 1000000000

feeRate.Type: string · int32

feeRate.Fee rate applied to the position, fp9 raw fraction (`1000000` = 0.1%).

feeRate.format: int32

feeRate.pattern: ^(?:-?[1-9][0-9]*|0)$

- exchangedQuote (string · int32; required)

exchangedQuote example: 1000000000

exchangedQuote.Type: string · int32

exchangedQuote.Quote amount exchanged by the most recent event, fp9 raw.

exchangedQuote.format: int32

exchangedQuote.pattern: ^(?:-?[1-9][0-9]*|0)$

- exchangedBase (string · int32; required)

exchangedBase example: 1000000000

exchangedBase.Type: string · int32

exchangedBase.Base amount exchanged by the most recent event, fp9 raw.

exchangedBase.format: int32

exchangedBase.pattern: ^(?:-?[1-9][0-9]*|0)$

- direction (string · enum; required)

direction example: long

direction.Type: string · enum

direction.Direction of the position.

direction.Allowed values: ["long","short"]

- eventName (string · enum; required)

eventName example: addMargin

eventName.Type: string · enum

eventName.Type of the most recent event applied to the position.

eventName.Allowed values: ["addMargin","removeMargin","closePosition","increasePosition","liquidate","forceClose","payFunding"]

- pnlInEvent (string · int32; required)

pnlInEvent example: 1000000000

pnlInEvent.Type: string · int32

pnlInEvent.Realised pnl of the most recent event, fp9 raw.

pnlInEvent.format: int32

pnlInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$

- rawPnlInEvent (string · int32; required)

rawPnlInEvent example: 1000000000

rawPnlInEvent.Type: string · int32

rawPnlInEvent.Realised pnl of the most recent event before the 60-second adjustment, fp9 raw. Differs from `pnlInEvent` only when the adjustment fired.

rawPnlInEvent.format: int32

rawPnlInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$

- profitAdjustmentApplied (boolean; required)

profitAdjustmentApplied example: true

profitAdjustmentApplied.Type: boolean

profitAdjustmentApplied.Whether the 60-second adjustment capped the profit of the most recent event — inside a minute of an open or increase the position pnl cannot grow above what it was at that moment.

- holdingTimeMs (string[]; required)

holdingTimeMs example: [
  "string"
]

holdingTimeMs.Type: string[]

holdingTimeMs.How long the position was held before the most recent close, in milliseconds, counted from the open or the last increase. Null on events that are not closes.

holdingTimeMs.[]Type: string

- feeInEvent (string · int32; required)

feeInEvent example: 1000000000

feeInEvent.Type: string · int32

feeInEvent.Fee charged by the most recent event, fp9 raw.

feeInEvent.format: int32

feeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$

- fundingInEvent (string · int32; required)

fundingInEvent example: 1000000000

fundingInEvent.Type: string · int32

fundingInEvent.Funding settled by the most recent event, fp9 raw.

fundingInEvent.format: int32

fundingInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$

- rolloverFeeInEvent (string · int32; required)

rolloverFeeInEvent example: 1000000000

rolloverFeeInEvent.Type: string · int32

rolloverFeeInEvent.Always `0`. Kept for backward compatibility.

rolloverFeeInEvent.format: int32

rolloverFeeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$

- executionFeeRate (string · int32; required)

executionFeeRate example: 1000000000

executionFeeRate.Type: string · int32

executionFeeRate.Always `0`. Kept for backward compatibility.

executionFeeRate.format: int32

executionFeeRate.pattern: ^(?:-?[1-9][0-9]*|0)$

- executionFeeInEvent (string · int32; required)

executionFeeInEvent example: 1000000000

executionFeeInEvent.Type: string · int32

executionFeeInEvent.Always `0`. Kept for backward compatibility.

executionFeeInEvent.format: int32

executionFeeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$

- executionFee (string · int32; required)

executionFee example: 1000000000

executionFee.Type: string · int32

executionFee.Always `0`. Kept for backward compatibility.

executionFee.format: int32

executionFee.pattern: ^(?:-?[1-9][0-9]*|0)$

- timestamp (string · date-time; required)

timestamp example: 2026-05-01T12:30:00.000Z

timestamp.Type: string · date-time

timestamp.Timestamp of the most recent event. Same value as `lastUpdatedAt`.

timestamp.format: date-time

- isOnchain (boolean; required)

isOnchain example: true

isOnchain.Type: boolean

isOnchain.Always `true`. Kept for backward compatibility.

- roe (string · int32; required)

roe example: 1000000000

roe.Type: string · int32

roe.Return on equity of the position — realised pnl over the margin put up, fp9 raw fraction.

roe.format: int32

roe.pattern: ^(?:-?[1-9][0-9]*|0)$

- scalpingCoefficient (string · int32; required)

scalpingCoefficient example: 1000000000

scalpingCoefficient.Type: string · int32

scalpingCoefficient.Dynamic spread multiplier the position was charged, fp9 raw (`1000000000` = 1.0). Above 1 when the trade fell inside the market scalping window.

scalpingCoefficient.format: int32

scalpingCoefficient.pattern: ^(?:-?[1-9][0-9]*|0)$

- closeReason (string[]; required)

closeReason example: [
  "string"
]

closeReason.Type: string[]

closeReason.Why the platform closed the position (for example `weekly_session_risk_close`). Null for positions closed by the trader and for open ones.

closeReason.[]Type: string

Example



```json
{
  "idx": [
    "string"
  ],
  "txId": [
    "string"
  ],
  "version": 0,
  "openedAt": "2026-05-01T12:30:00.000Z",
  "lastUpdatedAt": "2026-05-01T12:30:00.000Z",
  "closedAt": "2026-05-01T12:30:00.000Z",
  "type": "long",
  "status": "opened",
  "market": "00000000-0000-4000-8000-000000000000",
  "trader": "00000000-0000-4000-8000-000000000000",
  "size": "1000000000",
  "notional": "1000000000",
  "fraction": "1000000000",
  "margin": "1000000000",
  "pnl": "1000000000",
  "funding": "1000000000",
  "rolloverFee": "1000000000",
  "settlementOraclePrice": "1000000000",
  "fee": "1000000000",
  "feeRate": "1000000000",
  "exchangedQuote": "1000000000",
  "exchangedBase": "1000000000",
  "direction": "long",
  "eventName": "addMargin",
  "pnlInEvent": "1000000000",
  "rawPnlInEvent": "1000000000",
  "profitAdjustmentApplied": true,
  "holdingTimeMs": [
    "string"
  ],
  "feeInEvent": "1000000000",
  "fundingInEvent": "1000000000",
  "rolloverFeeInEvent": "1000000000",
  "executionFeeRate": "1000000000",
  "executionFeeInEvent": "1000000000",
  "executionFee": "1000000000",
  "timestamp": "2026-05-01T12:30:00.000Z",
  "isOnchain": true,
  "roe": "1000000000",
  "scalpingCoefficient": "1000000000",
  "closeReason": [
    "string"
  ]
}
```