{"format":"opendoc-document","version":1,"url":"https://docs.upscale.trade/developers/operations/changemargin","title":"Change position margin","description":"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.","kind":"api-operation","locale":"en","inLanguage":"en","lastModified":"2026-09-28T19:22:49.100Z","revision":"25c86f549328fcff320805d5945f4c9804e3927950d831e601d6e3b18c170f66","section":{"title":"Developers","url":"https://docs.upscale.trade/developers"},"representations":{"html":"https://docs.upscale.trade/developers/operations/changemargin","markdown":"https://docs.upscale.trade/developers/operations/changemargin.md","json":"https://docs.upscale.trade/developers/operations/changemargin.json"},"translations":{"en":"https://docs.upscale.trade/developers/operations/changemargin","ru":"https://docs.upscale.trade/ru/developers/operations/changemargin","es":"https://docs.upscale.trade/es/developers/operations/changemargin"},"operation":{"id":"changeMargin","method":"PATCH","path":"/positions/{positionId}/margin","summary":"Change position margin","description":"Moves quote balance in or out of the margin of an open position, which moves its leverage and liquidation price with it.\n\n- 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.\n- The market must be open and not in close-only mode.\n- `marginChange: \"0\"` is accepted and returns the position untouched.\n- Adding more than the free balance covers fails with `insufficient_balance`; withdrawing more than the position can spare fails with `non_positive_margin`.","tags":["Trading"],"deprecated":false,"parameters":[{"name":"positionId","location":"path","schema":{"type":"string · uuid","types":["string"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"uuid"},"properties":[],"variants":[]},"type":"string · uuid","required":true,"description":"Position identifier. Its account must belong to the caller.","example":"00000000-0000-4000-8000-000000000000"}],"bodies":[{"mediaType":"application/json","required":true,"properties":[{"name":"marginChange","type":"string · int32","required":true,"description":"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.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"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.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}}],"schema":{"type":"object","types":["object"],"reference":"#/components/schemas/MarginChangeRequest","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[{"name":"marginChange","type":"string · int32","required":true,"description":"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.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"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.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}}],"variants":[]},"example":"{\n  \"marginChange\": \"1000000000\"\n}"}],"responses":[{"status":"401","description":"Unauthorized","properties":[],"headers":[]},{"status":"403","description":"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`).","properties":[],"headers":[]},{"status":"404","description":"No position with this identifier.","properties":[],"headers":[]},{"status":"429","description":"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`.","properties":[],"headers":[]},{"status":"default","description":"Response","mediaType":"application/json","properties":[{"name":"idx","type":"string[]","required":true,"description":"Position identifier. Same value as `txId`.","example":"[\n  \"string\"\n]","schema":{"type":"string[]","types":["array"],"description":"Position identifier. Same value as `txId`.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"items":{"type":"string","types":["string"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]},"variants":[]}},{"name":"txId","type":"string[]","required":true,"description":"Position identifier. Kept for backward compatibility, always equal to `idx`.","example":"[\n  \"string\"\n]","schema":{"type":"string[]","types":["array"],"description":"Position identifier. Kept for backward compatibility, always equal to `idx`.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"items":{"type":"string","types":["string"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]},"variants":[]}},{"name":"version","type":"number","required":true,"description":"Revision of the position: incremented by every event applied to it.","example":"0","schema":{"type":"number","types":["number"],"description":"Revision of the position: incremented by every event applied to it.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"openedAt","type":"string · date-time","required":true,"description":"When the position was opened.","example":"2026-05-01T12:30:00.000Z","schema":{"type":"string · date-time","types":["string"],"description":"When the position was opened.","example":"2026-05-01T12:30:00.000Z","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"date-time"},"properties":[],"variants":[]}},{"name":"lastUpdatedAt","type":"string · date-time","required":true,"description":"When the last event was applied to the position.","example":"2026-05-01T12:30:00.000Z","schema":{"type":"string · date-time","types":["string"],"description":"When the last event was applied to the position.","example":"2026-05-01T12:30:00.000Z","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"date-time"},"properties":[],"variants":[]}},{"name":"closedAt","type":"string · date-time · nullable","required":true,"description":"When the position was closed; null while it is still open.","example":"2026-05-01T12:30:00.000Z","schema":{"type":"string · date-time · nullable","types":["string"],"description":"When the position was closed; null while it is still open.","example":"2026-05-01T12:30:00.000Z","nullable":true,"readOnly":false,"writeOnly":false,"constraints":{"format":"date-time"},"properties":[],"variants":[]}},{"name":"type","type":"string · enum","required":true,"description":"Direction of the position. Same value as `direction`.","example":"long","schema":{"type":"string · enum","types":["string"],"description":"Direction of the position. Same value as `direction`.","enum":["long","short"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"status","type":"string · enum","required":true,"description":"Whether the position is still open, closed by the trader, or liquidated.","example":"opened","schema":{"type":"string · enum","types":["string"],"description":"Whether the position is still open, closed by the trader, or liquidated.","enum":["opened","closed","liquidated"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"market","type":"string · uuid","required":true,"description":"Market the position is held on.","example":"00000000-0000-4000-8000-000000000000","schema":{"type":"string · uuid","types":["string"],"description":"Market the position is held on.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"uuid","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})$"},"properties":[],"variants":[]}},{"name":"trader","type":"string · uuid","required":true,"description":"Trader account the position belongs to.","example":"00000000-0000-4000-8000-000000000000","schema":{"type":"string · uuid","types":["string"],"description":"Trader account the position belongs to.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"uuid","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})$"},"properties":[],"variants":[]}},{"name":"size","type":"string · int32","required":true,"description":"Position size in base asset units, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Position size in base asset units, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"notional","type":"string · int32","required":true,"description":"Open notional of the position in quote currency, fp9 raw — size at entry price.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Open notional of the position in quote currency, fp9 raw — size at entry price.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"fraction","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"margin","type":"string · int32","required":true,"description":"Margin currently backing the position, fp9 raw. Moves with pnl, funding and manual margin changes.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Margin currently backing the position, fp9 raw. Moves with pnl, funding and manual margin changes.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"pnl","type":"string · int32 · nullable","required":true,"description":"Realised pnl accumulated over every event of the position, fp9 raw.","example":"1000000000","schema":{"type":"string · int32 · nullable","types":["string"],"description":"Realised pnl accumulated over every event of the position, fp9 raw.","example":"1000000000","nullable":true,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"funding","type":"string · int32 · nullable","required":true,"description":"Funding paid (negative) or received (positive) over the life of the position, fp9 raw.","example":"1000000000","schema":{"type":"string · int32 · nullable","types":["string"],"description":"Funding paid (negative) or received (positive) over the life of the position, fp9 raw.","example":"1000000000","nullable":true,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"rolloverFee","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"settlementOraclePrice","type":"string · int32","required":true,"description":"Always `1000000000` (1.0). Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `1000000000` (1.0). Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"fee","type":"string · int32","required":true,"description":"Trading fees charged over the life of the position, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Trading fees charged over the life of the position, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"feeRate","type":"string · int32","required":true,"description":"Fee rate applied to the position, fp9 raw fraction (`1000000` = 0.1%).","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Fee rate applied to the position, fp9 raw fraction (`1000000` = 0.1%).","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"exchangedQuote","type":"string · int32","required":true,"description":"Quote amount exchanged by the most recent event, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Quote amount exchanged by the most recent event, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"exchangedBase","type":"string · int32","required":true,"description":"Base amount exchanged by the most recent event, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Base amount exchanged by the most recent event, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"direction","type":"string · enum","required":true,"description":"Direction of the position.","example":"long","schema":{"type":"string · enum","types":["string"],"description":"Direction of the position.","enum":["long","short"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"eventName","type":"string · enum","required":true,"description":"Type of the most recent event applied to the position.","example":"addMargin","schema":{"type":"string · enum","types":["string"],"description":"Type of the most recent event applied to the position.","enum":["addMargin","removeMargin","closePosition","increasePosition","liquidate","forceClose","payFunding"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"pnlInEvent","type":"string · int32","required":true,"description":"Realised pnl of the most recent event, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Realised pnl of the most recent event, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"rawPnlInEvent","type":"string · int32","required":true,"description":"Realised pnl of the most recent event before the 60-second adjustment, fp9 raw. Differs from `pnlInEvent` only when the adjustment fired.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Realised pnl of the most recent event before the 60-second adjustment, fp9 raw. Differs from `pnlInEvent` only when the adjustment fired.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"profitAdjustmentApplied","type":"boolean","required":true,"description":"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.","example":"true","schema":{"type":"boolean","types":["boolean"],"description":"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.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"holdingTimeMs","type":"string[]","required":true,"description":"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.","example":"[\n  \"string\"\n]","schema":{"type":"string[]","types":["array"],"description":"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.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"items":{"type":"string","types":["string"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]},"variants":[]}},{"name":"feeInEvent","type":"string · int32","required":true,"description":"Fee charged by the most recent event, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Fee charged by the most recent event, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"fundingInEvent","type":"string · int32","required":true,"description":"Funding settled by the most recent event, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Funding settled by the most recent event, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"rolloverFeeInEvent","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"executionFeeRate","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"executionFeeInEvent","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"executionFee","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"timestamp","type":"string · date-time","required":true,"description":"Timestamp of the most recent event. Same value as `lastUpdatedAt`.","example":"2026-05-01T12:30:00.000Z","schema":{"type":"string · date-time","types":["string"],"description":"Timestamp of the most recent event. Same value as `lastUpdatedAt`.","example":"2026-05-01T12:30:00.000Z","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"date-time"},"properties":[],"variants":[]}},{"name":"isOnchain","type":"boolean","required":true,"description":"Always `true`. Kept for backward compatibility.","example":"true","schema":{"type":"boolean","types":["boolean"],"description":"Always `true`. Kept for backward compatibility.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"roe","type":"string · int32","required":true,"description":"Return on equity of the position — realised pnl over the margin put up, fp9 raw fraction.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Return on equity of the position — realised pnl over the margin put up, fp9 raw fraction.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"scalpingCoefficient","type":"string · int32","required":true,"description":"Dynamic spread multiplier the position was charged, fp9 raw (`1000000000` = 1.0). Above 1 when the trade fell inside the market scalping window.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Dynamic spread multiplier the position was charged, fp9 raw (`1000000000` = 1.0). Above 1 when the trade fell inside the market scalping window.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"closeReason","type":"string[]","required":true,"description":"Why the platform closed the position (for example `weekly_session_risk_close`). Null for positions closed by the trader and for open ones.","example":"[\n  \"string\"\n]","schema":{"type":"string[]","types":["array"],"description":"Why the platform closed the position (for example `weekly_session_risk_close`). Null for positions closed by the trader and for open ones.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"items":{"type":"string","types":["string"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]},"variants":[]}}],"schema":{"type":"object","types":["object"],"reference":"#/components/schemas/PositionResponse","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[{"name":"idx","type":"string[]","required":true,"description":"Position identifier. Same value as `txId`.","example":"[\n  \"string\"\n]","schema":{"type":"string[]","types":["array"],"description":"Position identifier. Same value as `txId`.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"items":{"type":"string","types":["string"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]},"variants":[]}},{"name":"txId","type":"string[]","required":true,"description":"Position identifier. Kept for backward compatibility, always equal to `idx`.","example":"[\n  \"string\"\n]","schema":{"type":"string[]","types":["array"],"description":"Position identifier. Kept for backward compatibility, always equal to `idx`.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"items":{"type":"string","types":["string"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]},"variants":[]}},{"name":"version","type":"number","required":true,"description":"Revision of the position: incremented by every event applied to it.","example":"0","schema":{"type":"number","types":["number"],"description":"Revision of the position: incremented by every event applied to it.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"openedAt","type":"string · date-time","required":true,"description":"When the position was opened.","example":"2026-05-01T12:30:00.000Z","schema":{"type":"string · date-time","types":["string"],"description":"When the position was opened.","example":"2026-05-01T12:30:00.000Z","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"date-time"},"properties":[],"variants":[]}},{"name":"lastUpdatedAt","type":"string · date-time","required":true,"description":"When the last event was applied to the position.","example":"2026-05-01T12:30:00.000Z","schema":{"type":"string · date-time","types":["string"],"description":"When the last event was applied to the position.","example":"2026-05-01T12:30:00.000Z","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"date-time"},"properties":[],"variants":[]}},{"name":"closedAt","type":"string · date-time · nullable","required":true,"description":"When the position was closed; null while it is still open.","example":"2026-05-01T12:30:00.000Z","schema":{"type":"string · date-time · nullable","types":["string"],"description":"When the position was closed; null while it is still open.","example":"2026-05-01T12:30:00.000Z","nullable":true,"readOnly":false,"writeOnly":false,"constraints":{"format":"date-time"},"properties":[],"variants":[]}},{"name":"type","type":"string · enum","required":true,"description":"Direction of the position. Same value as `direction`.","example":"long","schema":{"type":"string · enum","types":["string"],"description":"Direction of the position. Same value as `direction`.","enum":["long","short"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"status","type":"string · enum","required":true,"description":"Whether the position is still open, closed by the trader, or liquidated.","example":"opened","schema":{"type":"string · enum","types":["string"],"description":"Whether the position is still open, closed by the trader, or liquidated.","enum":["opened","closed","liquidated"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"market","type":"string · uuid","required":true,"description":"Market the position is held on.","example":"00000000-0000-4000-8000-000000000000","schema":{"type":"string · uuid","types":["string"],"description":"Market the position is held on.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"uuid","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})$"},"properties":[],"variants":[]}},{"name":"trader","type":"string · uuid","required":true,"description":"Trader account the position belongs to.","example":"00000000-0000-4000-8000-000000000000","schema":{"type":"string · uuid","types":["string"],"description":"Trader account the position belongs to.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"uuid","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})$"},"properties":[],"variants":[]}},{"name":"size","type":"string · int32","required":true,"description":"Position size in base asset units, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Position size in base asset units, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"notional","type":"string · int32","required":true,"description":"Open notional of the position in quote currency, fp9 raw — size at entry price.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Open notional of the position in quote currency, fp9 raw — size at entry price.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"fraction","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"margin","type":"string · int32","required":true,"description":"Margin currently backing the position, fp9 raw. Moves with pnl, funding and manual margin changes.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Margin currently backing the position, fp9 raw. Moves with pnl, funding and manual margin changes.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"pnl","type":"string · int32 · nullable","required":true,"description":"Realised pnl accumulated over every event of the position, fp9 raw.","example":"1000000000","schema":{"type":"string · int32 · nullable","types":["string"],"description":"Realised pnl accumulated over every event of the position, fp9 raw.","example":"1000000000","nullable":true,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"funding","type":"string · int32 · nullable","required":true,"description":"Funding paid (negative) or received (positive) over the life of the position, fp9 raw.","example":"1000000000","schema":{"type":"string · int32 · nullable","types":["string"],"description":"Funding paid (negative) or received (positive) over the life of the position, fp9 raw.","example":"1000000000","nullable":true,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"rolloverFee","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"settlementOraclePrice","type":"string · int32","required":true,"description":"Always `1000000000` (1.0). Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `1000000000` (1.0). Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"fee","type":"string · int32","required":true,"description":"Trading fees charged over the life of the position, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Trading fees charged over the life of the position, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"feeRate","type":"string · int32","required":true,"description":"Fee rate applied to the position, fp9 raw fraction (`1000000` = 0.1%).","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Fee rate applied to the position, fp9 raw fraction (`1000000` = 0.1%).","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"exchangedQuote","type":"string · int32","required":true,"description":"Quote amount exchanged by the most recent event, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Quote amount exchanged by the most recent event, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"exchangedBase","type":"string · int32","required":true,"description":"Base amount exchanged by the most recent event, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Base amount exchanged by the most recent event, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"direction","type":"string · enum","required":true,"description":"Direction of the position.","example":"long","schema":{"type":"string · enum","types":["string"],"description":"Direction of the position.","enum":["long","short"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"eventName","type":"string · enum","required":true,"description":"Type of the most recent event applied to the position.","example":"addMargin","schema":{"type":"string · enum","types":["string"],"description":"Type of the most recent event applied to the position.","enum":["addMargin","removeMargin","closePosition","increasePosition","liquidate","forceClose","payFunding"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"pnlInEvent","type":"string · int32","required":true,"description":"Realised pnl of the most recent event, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Realised pnl of the most recent event, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"rawPnlInEvent","type":"string · int32","required":true,"description":"Realised pnl of the most recent event before the 60-second adjustment, fp9 raw. Differs from `pnlInEvent` only when the adjustment fired.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Realised pnl of the most recent event before the 60-second adjustment, fp9 raw. Differs from `pnlInEvent` only when the adjustment fired.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"profitAdjustmentApplied","type":"boolean","required":true,"description":"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.","example":"true","schema":{"type":"boolean","types":["boolean"],"description":"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.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"holdingTimeMs","type":"string[]","required":true,"description":"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.","example":"[\n  \"string\"\n]","schema":{"type":"string[]","types":["array"],"description":"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.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"items":{"type":"string","types":["string"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]},"variants":[]}},{"name":"feeInEvent","type":"string · int32","required":true,"description":"Fee charged by the most recent event, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Fee charged by the most recent event, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"fundingInEvent","type":"string · int32","required":true,"description":"Funding settled by the most recent event, fp9 raw.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Funding settled by the most recent event, fp9 raw.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"rolloverFeeInEvent","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"executionFeeRate","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"executionFeeInEvent","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"executionFee","type":"string · int32","required":true,"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Always `0`. Kept for backward compatibility.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"timestamp","type":"string · date-time","required":true,"description":"Timestamp of the most recent event. Same value as `lastUpdatedAt`.","example":"2026-05-01T12:30:00.000Z","schema":{"type":"string · date-time","types":["string"],"description":"Timestamp of the most recent event. Same value as `lastUpdatedAt`.","example":"2026-05-01T12:30:00.000Z","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"date-time"},"properties":[],"variants":[]}},{"name":"isOnchain","type":"boolean","required":true,"description":"Always `true`. Kept for backward compatibility.","example":"true","schema":{"type":"boolean","types":["boolean"],"description":"Always `true`. Kept for backward compatibility.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]}},{"name":"roe","type":"string · int32","required":true,"description":"Return on equity of the position — realised pnl over the margin put up, fp9 raw fraction.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Return on equity of the position — realised pnl over the margin put up, fp9 raw fraction.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"scalpingCoefficient","type":"string · int32","required":true,"description":"Dynamic spread multiplier the position was charged, fp9 raw (`1000000000` = 1.0). Above 1 when the trade fell inside the market scalping window.","example":"1000000000","schema":{"type":"string · int32","types":["string"],"description":"Dynamic spread multiplier the position was charged, fp9 raw (`1000000000` = 1.0). Above 1 when the trade fell inside the market scalping window.","example":"1000000000","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{"format":"int32","pattern":"^(?:-?[1-9][0-9]*|0)$"},"properties":[],"variants":[]}},{"name":"closeReason","type":"string[]","required":true,"description":"Why the platform closed the position (for example `weekly_session_risk_close`). Null for positions closed by the trader and for open ones.","example":"[\n  \"string\"\n]","schema":{"type":"string[]","types":["array"],"description":"Why the platform closed the position (for example `weekly_session_risk_close`). Null for positions closed by the trader and for open ones.","nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"items":{"type":"string","types":["string"],"nullable":false,"readOnly":false,"writeOnly":false,"constraints":{},"properties":[],"variants":[]},"variants":[]}}],"variants":[]},"example":"{\n  \"idx\": [\n    \"string\"\n  ],\n  \"txId\": [\n    \"string\"\n  ],\n  \"version\": 0,\n  \"openedAt\": \"2026-05-01T12:30:00.000Z\",\n  \"lastUpdatedAt\": \"2026-05-01T12:30:00.000Z\",\n  \"closedAt\": \"2026-05-01T12:30:00.000Z\",\n  \"type\": \"long\",\n  \"status\": \"opened\",\n  \"market\": \"00000000-0000-4000-8000-000000000000\",\n  \"trader\": \"00000000-0000-4000-8000-000000000000\",\n  \"size\": \"1000000000\",\n  \"notional\": \"1000000000\",\n  \"fraction\": \"1000000000\",\n  \"margin\": \"1000000000\",\n  \"pnl\": \"1000000000\",\n  \"funding\": \"1000000000\",\n  \"rolloverFee\": \"1000000000\",\n  \"settlementOraclePrice\": \"1000000000\",\n  \"fee\": \"1000000000\",\n  \"feeRate\": \"1000000000\",\n  \"exchangedQuote\": \"1000000000\",\n  \"exchangedBase\": \"1000000000\",\n  \"direction\": \"long\",\n  \"eventName\": \"addMargin\",\n  \"pnlInEvent\": \"1000000000\",\n  \"rawPnlInEvent\": \"1000000000\",\n  \"profitAdjustmentApplied\": true,\n  \"holdingTimeMs\": [\n    \"string\"\n  ],\n  \"feeInEvent\": \"1000000000\",\n  \"fundingInEvent\": \"1000000000\",\n  \"rolloverFeeInEvent\": \"1000000000\",\n  \"executionFeeRate\": \"1000000000\",\n  \"executionFeeInEvent\": \"1000000000\",\n  \"executionFee\": \"1000000000\",\n  \"timestamp\": \"2026-05-01T12:30:00.000Z\",\n  \"isOnchain\": true,\n  \"roe\": \"1000000000\",\n  \"scalpingCoefficient\": \"1000000000\",\n  \"closeReason\": [\n    \"string\"\n  ]\n}","headers":[]}],"security":[{"name":"bearer","type":"http · bearer","description":"Personal API key, prefixed with `usk_`.","required":true,"scopes":[]}],"codeSamples":[{"label":"cURL","language":"bash","source":"curl --request PATCH 'https://api.upscale.trade/positions/{positionId}/margin' \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data-raw '{\n  \"marginChange\": \"1000000000\"\n}'"},{"label":"JavaScript","language":"javascript","source":"const response = await fetch(\"https://api.upscale.trade/positions/{positionId}/margin\", {\n  method: \"PATCH\",\n  headers: {\n    \"Accept\": \"application/json\",\n    \"Authorization\": \"Bearer YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: \"{\\n  \\\"marginChange\\\": \\\"1000000000\\\"\\n}\",\n});\nconsole.log(response.status, await response.text());"},{"label":"Python","language":"python","source":"import requests\n\nresponse = requests.request(\n    \"PATCH\",\n    \"https://api.upscale.trade/positions/{positionId}/margin\",\n    headers={\"Accept\":\"application/json\",\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"},\n    data=\"{\\n  \\\"marginChange\\\": \\\"1000000000\\\"\\n}\",\n    timeout=30,\n)\nprint(response.status_code, response.text)"}]},"breadcrumbs":[{"title":"What is Prop Trading","url":"https://docs.upscale.trade"},{"title":"Developers","url":"https://docs.upscale.trade/developers"},{"title":"Change position margin","url":"https://docs.upscale.trade/developers/operations/changemargin"}],"headings":[{"depth":2,"id":"authorization","title":"Authorization"},{"depth":2,"id":"parameters","title":"Parameters"},{"depth":2,"id":"request-body-required","title":"Request body · required"},{"depth":2,"id":"examples","title":"Examples"},{"depth":2,"id":"responses","title":"Responses"}],"markdown":"# Change position margin\n\n`PATCH /positions/{positionId}/margin`\n\nMoves quote balance in or out of the margin of an open position, which moves its leverage and liquidation price with it.\n\n- 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.\n- The market must be open and not in close-only mode.\n- `marginChange: \"0\"` is accepted and returns the position untouched.\n- Adding more than the free balance covers fails with `insufficient_balance`; withdrawing more than the position can spare fails with `non_positive_margin`.\n\n## Authorization\n\nbearer: http · bearer (required). Personal API key, prefixed with `usk_`.\n\n## Parameters\n\n- path: positionId (string · uuid; required). Position identifier. Its account must belong to the caller.\n\nType: string · uuid\n\nformat: uuid\n\n## Request body · MarginChangeRequest\n\napplication/json · required\n\nSchema: MarginChangeRequest\n\nType: object\n\nRequired fields: marginChange\n\nRequired field types: marginChange (string · int32; required)\n\n- marginChange (string · int32; required)\n\nmarginChange example: 1000000000\n\nmarginChange.Type: string · int32\n\nmarginChange.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.\n\nmarginChange.format: int32\n\nmarginChange.pattern: ^(?:-?[1-9][0-9]*|0)$\n\nExample\n\n\n\n```json\n{\n  \"marginChange\": \"1000000000\"\n}\n```\n\n## Example · cURL\n\n```bash\ncurl --request PATCH 'https://api.upscale.trade/positions/{positionId}/margin' \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'Content-Type: application/json' \\\n  --data-raw '{\n  \"marginChange\": \"1000000000\"\n}'\n```\n\n## Example · JavaScript\n\n```javascript\nconst response = await fetch(\"https://api.upscale.trade/positions/{positionId}/margin\", {\n  method: \"PATCH\",\n  headers: {\n    \"Accept\": \"application/json\",\n    \"Authorization\": \"Bearer YOUR_API_KEY\",\n    \"Content-Type\": \"application/json\"\n  },\n  body: \"{\\n  \\\"marginChange\\\": \\\"1000000000\\\"\\n}\",\n});\nconsole.log(response.status, await response.text());\n```\n\n## Example · Python\n\n```python\nimport requests\n\nresponse = requests.request(\n    \"PATCH\",\n    \"https://api.upscale.trade/positions/{positionId}/margin\",\n    headers={\"Accept\":\"application/json\",\"Authorization\":\"Bearer YOUR_API_KEY\",\"Content-Type\":\"application/json\"},\n    data=\"{\\n  \\\"marginChange\\\": \\\"1000000000\\\"\\n}\",\n    timeout=30,\n)\nprint(response.status_code, response.text)\n```\n\n## Response 401\n\n**401**  — Unauthorized\n\n## Response 403\n\n**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`).\n\n## Response 404\n\n**404**  — No position with this identifier.\n\n## Response 429\n\n**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`.\n\n## Response default · PositionResponse\n\n**default** application/json — Response\n\nSchema: PositionResponse\n\nType: object\n\nRequired 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\n\nRequired 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)\n\n- idx (string[]; required)\n\nidx example: [\n  \"string\"\n]\n\nidx.Type: string[]\n\nidx.Position identifier. Same value as `txId`.\n\nidx.[]Type: string\n\n- txId (string[]; required)\n\ntxId example: [\n  \"string\"\n]\n\ntxId.Type: string[]\n\ntxId.Position identifier. Kept for backward compatibility, always equal to `idx`.\n\ntxId.[]Type: string\n\n- version (number; required)\n\nversion example: 0\n\nversion.Type: number\n\nversion.Revision of the position: incremented by every event applied to it.\n\n- openedAt (string · date-time; required)\n\nopenedAt example: 2026-05-01T12:30:00.000Z\n\nopenedAt.Type: string · date-time\n\nopenedAt.When the position was opened.\n\nopenedAt.format: date-time\n\n- lastUpdatedAt (string · date-time; required)\n\nlastUpdatedAt example: 2026-05-01T12:30:00.000Z\n\nlastUpdatedAt.Type: string · date-time\n\nlastUpdatedAt.When the last event was applied to the position.\n\nlastUpdatedAt.format: date-time\n\n- closedAt (string · date-time · nullable; required)\n\nclosedAt example: 2026-05-01T12:30:00.000Z\n\nclosedAt.Type: string · date-time · nullable\n\nclosedAt.When the position was closed; null while it is still open.\n\nclosedAt.format: date-time\n\n- type (string · enum; required)\n\ntype example: long\n\ntype.Type: string · enum\n\ntype.Direction of the position. Same value as `direction`.\n\ntype.Allowed values: [\"long\",\"short\"]\n\n- status (string · enum; required)\n\nstatus example: opened\n\nstatus.Type: string · enum\n\nstatus.Whether the position is still open, closed by the trader, or liquidated.\n\nstatus.Allowed values: [\"opened\",\"closed\",\"liquidated\"]\n\n- market (string · uuid; required)\n\nmarket example: 00000000-0000-4000-8000-000000000000\n\nmarket.Type: string · uuid\n\nmarket.Market the position is held on.\n\nmarket.format: uuid\n\nmarket.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})$\n\n- trader (string · uuid; required)\n\ntrader example: 00000000-0000-4000-8000-000000000000\n\ntrader.Type: string · uuid\n\ntrader.Trader account the position belongs to.\n\ntrader.format: uuid\n\ntrader.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})$\n\n- size (string · int32; required)\n\nsize example: 1000000000\n\nsize.Type: string · int32\n\nsize.Position size in base asset units, fp9 raw.\n\nsize.format: int32\n\nsize.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- notional (string · int32; required)\n\nnotional example: 1000000000\n\nnotional.Type: string · int32\n\nnotional.Open notional of the position in quote currency, fp9 raw — size at entry price.\n\nnotional.format: int32\n\nnotional.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- fraction (string · int32; required)\n\nfraction example: 1000000000\n\nfraction.Type: string · int32\n\nfraction.Always `0`. Kept for backward compatibility.\n\nfraction.format: int32\n\nfraction.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- margin (string · int32; required)\n\nmargin example: 1000000000\n\nmargin.Type: string · int32\n\nmargin.Margin currently backing the position, fp9 raw. Moves with pnl, funding and manual margin changes.\n\nmargin.format: int32\n\nmargin.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- pnl (string · int32 · nullable; required)\n\npnl example: 1000000000\n\npnl.Type: string · int32 · nullable\n\npnl.Realised pnl accumulated over every event of the position, fp9 raw.\n\npnl.format: int32\n\npnl.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- funding (string · int32 · nullable; required)\n\nfunding example: 1000000000\n\nfunding.Type: string · int32 · nullable\n\nfunding.Funding paid (negative) or received (positive) over the life of the position, fp9 raw.\n\nfunding.format: int32\n\nfunding.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- rolloverFee (string · int32; required)\n\nrolloverFee example: 1000000000\n\nrolloverFee.Type: string · int32\n\nrolloverFee.Always `0`. Kept for backward compatibility.\n\nrolloverFee.format: int32\n\nrolloverFee.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- settlementOraclePrice (string · int32; required)\n\nsettlementOraclePrice example: 1000000000\n\nsettlementOraclePrice.Type: string · int32\n\nsettlementOraclePrice.Always `1000000000` (1.0). Kept for backward compatibility.\n\nsettlementOraclePrice.format: int32\n\nsettlementOraclePrice.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- fee (string · int32; required)\n\nfee example: 1000000000\n\nfee.Type: string · int32\n\nfee.Trading fees charged over the life of the position, fp9 raw.\n\nfee.format: int32\n\nfee.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- feeRate (string · int32; required)\n\nfeeRate example: 1000000000\n\nfeeRate.Type: string · int32\n\nfeeRate.Fee rate applied to the position, fp9 raw fraction (`1000000` = 0.1%).\n\nfeeRate.format: int32\n\nfeeRate.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- exchangedQuote (string · int32; required)\n\nexchangedQuote example: 1000000000\n\nexchangedQuote.Type: string · int32\n\nexchangedQuote.Quote amount exchanged by the most recent event, fp9 raw.\n\nexchangedQuote.format: int32\n\nexchangedQuote.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- exchangedBase (string · int32; required)\n\nexchangedBase example: 1000000000\n\nexchangedBase.Type: string · int32\n\nexchangedBase.Base amount exchanged by the most recent event, fp9 raw.\n\nexchangedBase.format: int32\n\nexchangedBase.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- direction (string · enum; required)\n\ndirection example: long\n\ndirection.Type: string · enum\n\ndirection.Direction of the position.\n\ndirection.Allowed values: [\"long\",\"short\"]\n\n- eventName (string · enum; required)\n\neventName example: addMargin\n\neventName.Type: string · enum\n\neventName.Type of the most recent event applied to the position.\n\neventName.Allowed values: [\"addMargin\",\"removeMargin\",\"closePosition\",\"increasePosition\",\"liquidate\",\"forceClose\",\"payFunding\"]\n\n- pnlInEvent (string · int32; required)\n\npnlInEvent example: 1000000000\n\npnlInEvent.Type: string · int32\n\npnlInEvent.Realised pnl of the most recent event, fp9 raw.\n\npnlInEvent.format: int32\n\npnlInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- rawPnlInEvent (string · int32; required)\n\nrawPnlInEvent example: 1000000000\n\nrawPnlInEvent.Type: string · int32\n\nrawPnlInEvent.Realised pnl of the most recent event before the 60-second adjustment, fp9 raw. Differs from `pnlInEvent` only when the adjustment fired.\n\nrawPnlInEvent.format: int32\n\nrawPnlInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- profitAdjustmentApplied (boolean; required)\n\nprofitAdjustmentApplied example: true\n\nprofitAdjustmentApplied.Type: boolean\n\nprofitAdjustmentApplied.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.\n\n- holdingTimeMs (string[]; required)\n\nholdingTimeMs example: [\n  \"string\"\n]\n\nholdingTimeMs.Type: string[]\n\nholdingTimeMs.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.\n\nholdingTimeMs.[]Type: string\n\n- feeInEvent (string · int32; required)\n\nfeeInEvent example: 1000000000\n\nfeeInEvent.Type: string · int32\n\nfeeInEvent.Fee charged by the most recent event, fp9 raw.\n\nfeeInEvent.format: int32\n\nfeeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- fundingInEvent (string · int32; required)\n\nfundingInEvent example: 1000000000\n\nfundingInEvent.Type: string · int32\n\nfundingInEvent.Funding settled by the most recent event, fp9 raw.\n\nfundingInEvent.format: int32\n\nfundingInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- rolloverFeeInEvent (string · int32; required)\n\nrolloverFeeInEvent example: 1000000000\n\nrolloverFeeInEvent.Type: string · int32\n\nrolloverFeeInEvent.Always `0`. Kept for backward compatibility.\n\nrolloverFeeInEvent.format: int32\n\nrolloverFeeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- executionFeeRate (string · int32; required)\n\nexecutionFeeRate example: 1000000000\n\nexecutionFeeRate.Type: string · int32\n\nexecutionFeeRate.Always `0`. Kept for backward compatibility.\n\nexecutionFeeRate.format: int32\n\nexecutionFeeRate.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- executionFeeInEvent (string · int32; required)\n\nexecutionFeeInEvent example: 1000000000\n\nexecutionFeeInEvent.Type: string · int32\n\nexecutionFeeInEvent.Always `0`. Kept for backward compatibility.\n\nexecutionFeeInEvent.format: int32\n\nexecutionFeeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- executionFee (string · int32; required)\n\nexecutionFee example: 1000000000\n\nexecutionFee.Type: string · int32\n\nexecutionFee.Always `0`. Kept for backward compatibility.\n\nexecutionFee.format: int32\n\nexecutionFee.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- timestamp (string · date-time; required)\n\ntimestamp example: 2026-05-01T12:30:00.000Z\n\ntimestamp.Type: string · date-time\n\ntimestamp.Timestamp of the most recent event. Same value as `lastUpdatedAt`.\n\ntimestamp.format: date-time\n\n- isOnchain (boolean; required)\n\nisOnchain example: true\n\nisOnchain.Type: boolean\n\nisOnchain.Always `true`. Kept for backward compatibility.\n\n- roe (string · int32; required)\n\nroe example: 1000000000\n\nroe.Type: string · int32\n\nroe.Return on equity of the position — realised pnl over the margin put up, fp9 raw fraction.\n\nroe.format: int32\n\nroe.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- scalpingCoefficient (string · int32; required)\n\nscalpingCoefficient example: 1000000000\n\nscalpingCoefficient.Type: string · int32\n\nscalpingCoefficient.Dynamic spread multiplier the position was charged, fp9 raw (`1000000000` = 1.0). Above 1 when the trade fell inside the market scalping window.\n\nscalpingCoefficient.format: int32\n\nscalpingCoefficient.pattern: ^(?:-?[1-9][0-9]*|0)$\n\n- closeReason (string[]; required)\n\ncloseReason example: [\n  \"string\"\n]\n\ncloseReason.Type: string[]\n\ncloseReason.Why the platform closed the position (for example `weekly_session_risk_close`). Null for positions closed by the trader and for open ones.\n\ncloseReason.[]Type: string\n\nExample\n\n\n\n```json\n{\n  \"idx\": [\n    \"string\"\n  ],\n  \"txId\": [\n    \"string\"\n  ],\n  \"version\": 0,\n  \"openedAt\": \"2026-05-01T12:30:00.000Z\",\n  \"lastUpdatedAt\": \"2026-05-01T12:30:00.000Z\",\n  \"closedAt\": \"2026-05-01T12:30:00.000Z\",\n  \"type\": \"long\",\n  \"status\": \"opened\",\n  \"market\": \"00000000-0000-4000-8000-000000000000\",\n  \"trader\": \"00000000-0000-4000-8000-000000000000\",\n  \"size\": \"1000000000\",\n  \"notional\": \"1000000000\",\n  \"fraction\": \"1000000000\",\n  \"margin\": \"1000000000\",\n  \"pnl\": \"1000000000\",\n  \"funding\": \"1000000000\",\n  \"rolloverFee\": \"1000000000\",\n  \"settlementOraclePrice\": \"1000000000\",\n  \"fee\": \"1000000000\",\n  \"feeRate\": \"1000000000\",\n  \"exchangedQuote\": \"1000000000\",\n  \"exchangedBase\": \"1000000000\",\n  \"direction\": \"long\",\n  \"eventName\": \"addMargin\",\n  \"pnlInEvent\": \"1000000000\",\n  \"rawPnlInEvent\": \"1000000000\",\n  \"profitAdjustmentApplied\": true,\n  \"holdingTimeMs\": [\n    \"string\"\n  ],\n  \"feeInEvent\": \"1000000000\",\n  \"fundingInEvent\": \"1000000000\",\n  \"rolloverFeeInEvent\": \"1000000000\",\n  \"executionFeeRate\": \"1000000000\",\n  \"executionFeeInEvent\": \"1000000000\",\n  \"executionFee\": \"1000000000\",\n  \"timestamp\": \"2026-05-01T12:30:00.000Z\",\n  \"isOnchain\": true,\n  \"roe\": \"1000000000\",\n  \"scalpingCoefficient\": \"1000000000\",\n  \"closeReason\": [\n    \"string\"\n  ]\n}\n```","text":"Change position 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`. PATCH /positions/{positionId}/margin Trading positionId Position identifier. Its account must belong to the caller. string · uuid 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. string · int32 401 Unauthorized 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`). 404 No position with this identifier. 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`. default Response idx Position identifier. Same value as `txId`. string[] txId Position identifier. Kept for backward compatibility, always equal to `idx`. string[] version Revision of the position: incremented by every event applied to it. number openedAt When the position was opened. string · date-time lastUpdatedAt When the last event was applied to the position. string · date-time closedAt When the position was closed; null while it is still open. string · date-time · nullable type Direction of the position. Same value as `direction`. string · enum status Whether the position is still open, closed by the trader, or liquidated. string · enum market Market the position is held on. string · uuid trader Trader account the position belongs to. string · uuid size Position size in base asset units, fp9 raw. string · int32 notional Open notional of the position in quote currency, fp9 raw — size at entry price. string · int32 fraction Always `0`. Kept for backward compatibility. string · int32 margin Margin currently backing the position, fp9 raw. Moves with pnl, funding and manual margin changes. string · int32 pnl Realised pnl accumulated over every event of the position, fp9 raw. string · int32 · nullable funding Funding paid (negative) or received (positive) over the life of the position, fp9 raw. string · int32 · nullable rolloverFee Always `0`. Kept for backward compatibility. string · int32 settlementOraclePrice Always `1000000000` (1.0). Kept for backward compatibility. string · int32 fee Trading fees charged over the life of the position, fp9 raw. string · int32 feeRate Fee rate applied to the position, fp9 raw fraction (`1000000` = 0.1%). string · int32 exchangedQuote Quote amount exchanged by the most recent event, fp9 raw. string · int32 exchangedBase Base amount exchanged by the most recent event, fp9 raw. string · int32 direction Direction of the position. string · enum eventName Type of the most recent event applied to the position. string · enum pnlInEvent Realised pnl of the most recent event, fp9 raw. 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. string · int32 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. boolean 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. string[] feeInEvent Fee charged by the most recent event, fp9 raw. string · int32 fundingInEvent Funding settled by the most recent event, fp9 raw. string · int32 rolloverFeeInEvent Always `0`. Kept for backward compatibility. string · int32 executionFeeRate Always `0`. Kept for backward compatibility. string · int32 executionFeeInEvent Always `0`. Kept for backward compatibility. string · int32 executionFee Always `0`. Kept for backward compatibility. string · int32 timestamp Timestamp of the most recent event. Same value as `lastUpdatedAt`. string · date-time isOnchain Always `true`. Kept for backward compatibility. boolean roe Return on equity of the position — realised pnl over the margin put up, fp9 raw fraction. 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. string · int32 closeReason Why the platform closed the position (for example `weekly_session_risk_close`). Null for positions closed by the trader and for open ones. string[]","api":{"title":"Upscale Public API","version":"d796ac9","documentation":"https://docs.upscale.trade/developers","playgroundServer":"https://api.upscale.trade"}}