Skip to main content
POST
Build a transaction that adds or removes position collateral

Body

application/json
trader
string
required

The trader (position owner). USDC collateral is pulled from and paid out to this address.

tradeIndex
integer
required

Position slot index for this trader + pair (0-based; a trader can hold several positions on the same pair). Read it from GET /v2/positions → trades[].trade.index.

Required range: x >= 0
action
enum<string>
required

deposit adds collateral to the position, withdraw removes it.

Available options:
deposit,
withdraw
collateralUsdc
required

USDC to add to or remove from the position's margin.

pairIndex
integer

Pair index (alternative to pair).

Required range: x >= 0
pair
string

Pair symbol, e.g. ETH/USD (separators /, -, _ accepted; case-insensitive).

Minimum string length: 1
delegate
string

Optional pre-authorized delegate. When set, the call is wrapped in delegatedAction(trader, …) and from becomes this address — the delegate signs the transaction and pays gas. Register one via /v2/delegate/set.

priceUpdateData
string

Pre-fetched oracle price-update bytes (0x hex). Fetched from the Avantis price feed automatically when omitted.

Pattern: ^0x[0-9a-fA-F]*$
priceSourcing

Price oracle leg: 0 = Pyth Hermes (core), 1 = Pyth Lazer (pro). Auto-detected when omitted.

Available options:
0
oracleFeeWei

Oracle update fee attached as msg.value (NOT an operator fee). Default 1 wei.

Response

Success envelope: ok is true and data carries the payload documented below.

ok
enum<boolean>
required

Always true on success.

Available options:
true
data
object
required

An unsigned EVM transaction. Sign it with the from key and broadcast it yourself, or submit the signed bytes via POST /v2/relay.