> ## Documentation Index > Fetch the complete documentation index at: https://docs.raze.bot/llms.txt > Use this file to discover all available pages before exploring further. # Edit position collateral > Add or withdraw margin on an existing **Jupiter Perps** position without changing its size — the venue's "Edit Collateral" operation. `action: "add"` deposits in the side's native collateral mint at the live oracle price; `action: "withdraw"` pays out in USDC like a close. The position PDA is derived **server-side** per wallet and is never client-supplied. Idempotent on `client_order_id` for 60s, like every other `/perp/sol/*` write. When the fleet's shared idempotency cache is configured, a request already served by another edge answers **409** instead of rebuilding. ## OpenAPI ````yaml openapi-spec/trading.yaml post /perp/sol/collateral openapi: 3.0.3 info: title: Raze Trading API description: > Trading endpoints for Solana token swaps — quote, buy, sell, atomic round-trips and raw instructions. Perpetuals (Jupiter Perps + Phoenix) live here too. Quotes can also be **streamed**: `/swap/sol/quote/stream` is a WebSocket that pushes a fresh quote whenever the pools under your route move. It is not describable in OpenAPI — see [Streaming quotes](/api-reference/router/quote-stream). Write utilities (`/utils/sol/*` — launch, transfer, burn, consolidate, fees) moved to the History API on `https://api.raze.bot` (see `history.yaml`). Runs on port 8082. **Auth methods**: `Authorization: Bearer sk_...` header, `X-API-Key: sk_...` header, or `?apiKey=sk_...` query param. version: 2.1.0 servers: - url: https://router.raze.bot description: >- Raze global trading router — GeoDNS routes to the nearest region automatically security: [] paths: /perp/sol/collateral: post: summary: Edit position collateral description: > Add or withdraw margin on an existing **Jupiter Perps** position without changing its size — the venue's "Edit Collateral" operation. `action: "add"` deposits in the side's native collateral mint at the live oracle price; `action: "withdraw"` pays out in USDC like a close. The position PDA is derived **server-side** per wallet and is never client-supplied. Idempotent on `client_order_id` for 60s, like every other `/perp/sol/*` write. When the fleet's shared idempotency cache is configured, a request already served by another edge answers **409** instead of rebuilding. operationId: perpCollateral requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PerpCollateralRequest' examples: addMargin: summary: Add $50 of margin to a SOL long value: wallet_addresses: - 62ThHC1rs2GUfa8J4Qjcj5GD2MSL2d65pcJtenNieDnm market_id: jup:SOL-PERP side: long action: add amount_usd_e6: 50000000 slippage_bps: 50 client_order_id: ui-collat-20260728-a1 withdrawMargin: summary: Withdraw $25 of margin value: wallet_addresses: - 62ThHC1rs2GUfa8J4Qjcj5GD2MSL2d65pcJtenNieDnm market_id: jup:SOL-PERP side: long action: withdraw amount_usd_e6: 25000000 slippage_bps: 50 client_order_id: ui-collat-20260728-w1 responses: '200': description: Transactions built content: application/json: schema: $ref: '#/components/schemas/PerpTxResponse' '400': description: >- Invalid request (missing client_order_id, unknown action, zero amount_usd_e6, slippage_bps ≥ 10000, bad market_id/wallet) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- Duplicate — this `client_order_id` was already served by another edge content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Builder error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: PerpCollateralRequest: type: object required: - wallet_addresses - market_id - side - action - amount_usd_e6 - slippage_bps - client_order_id properties: wallet_addresses: type: array items: type: string minItems: 1 market_id: type: string example: jup:SOL-PERP side: type: string enum: - long - short description: Side of the open position — picks the collateral custody account. action: type: string enum: - add - withdraw description: > `add` deposits margin in the side's native collateral mint at the live oracle price; `withdraw` pays out in USDC like a close. amount_usd_e6: type: integer format: int64 description: USD value to move, in USDC micros. Must be > 0. slippage_bps: type: integer description: Must be < 10000. client_order_id: type: string description: >- Caller-supplied idempotency key (60s window), same contract as `/perp/sol/order`. PerpTxResponse: type: object properties: success: type: boolean data: type: array items: $ref: '#/components/schemas/PerpTx' error: type: string ErrorResponse: type: object properties: success: type: boolean example: false error: type: string details: type: string required: - success - error PerpTx: type: object description: One unsigned transaction per wallet in the request. properties: wallet: type: string tx_b64: type: string description: Base64-encoded unsigned versioned transaction. status: type: string description: >- Builder-side hint (e.g. `created`, `funded_swap`, `phoenix-deposit`). position_request: type: string description: | `position_request` PDA this transaction creates or targets (Jupiter builds only). Lets a client cancel a stuck request without a History API round-trip. The PDA counter is derived deterministically from `client_order_id`, so the same request rebuilt on another edge lands on the same PDA — exactly-once on-chain. counter: type: integer format: int64 description: PDA counter used to derive `position_request` (create paths only). position: type: string description: Position PDA the request acts on. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer ````