Positions

List processed open positions

get

Returns processed open positions for the authenticated user

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Processed open positions fetched successfully

application/json

positionIdstringRequired

Position identifier

addressstringRequired

User wallet address

pearExecutionFlagstring · enumRequired

Pear execution flag

Possible values:

entryRationumberRequired

Weighted entry ratio

Example: 1.02

markRationumberRequired

Weighted mark ratio

Example: 1.01

entryPriceRationumberOptional

Entry price ratio (only for 1 long x 1 short)

markPriceRationumberOptional

Mark price ratio (only for 1 long x 1 short)

entryPositionValuenumberRequired

Total entry USD value

Example: 10000

positionValuenumberRequired

Total current USD value

Example: 10200

marginUsednumberRequired

Total margin used

Example: 2000

unrealizedPnlnumberRequired

Total unrealized PnL (USD)

Example: 200

unrealizedPnlPercentagenumberRequired

Unrealized PnL percentage relative to margin used

Example: 0.1

createdAtstring · date-timeRequired

Creation timestamp

updatedAtstring · date-timeRequired

Last update timestamp

get

/positions

HTTPcURLJavaScriptPython

GET /positions HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Processed open positions fetched successfully

[
  {
    "positionId": "text",
    "address": "text",
    "pearExecutionFlag": "FULLY_PEAR",
    "stopLoss": {
      "type": "PERCENTAGE",
      "value": 15,
      "isTrailing": false,
      "trailingDeltaValue": 5,
      "trailingActivationValue": 50000
    },
    "takeProfit": {
      "type": "PERCENTAGE",
      "value": 15,
      "isTrailing": false,
      "trailingDeltaValue": 5,
      "trailingActivationValue": 50000
    },
    "entryRatio": 1.02,
    "markRatio": 1.01,
    "entryPriceRatio": 1,
    "markPriceRatio": 1,
    "entryPositionValue": 10000,
    "positionValue": 10200,
    "marginUsed": 2000,
    "unrealizedPnl": 200,
    "unrealizedPnlPercentage": 0.1,
    "longAssets": [
      {
        "coin": "BTC",
        "entryPrice": 50000,
        "actualSize": 0.1,
        "leverage": 5,
        "marginUsed": 5000,
        "positionValue": 5200,
        "unrealizedPnl": 200,
        "entryPositionValue": 5000,
        "fundingPaid": -3.25,
        "targetWeight": 0.5
      }
    ],
    "shortAssets": [
      {
        "coin": "BTC",
        "entryPrice": 50000,
        "actualSize": 0.1,
        "leverage": 5,
        "marginUsed": 5000,
        "positionValue": 5200,
        "unrealizedPnl": 200,
        "entryPositionValue": 5000,
        "fundingPaid": -3.25,
        "targetWeight": 0.5
      }
    ],
    "createdAt": "2026-06-08T15:15:35.321Z",
    "updatedAt": "2026-06-08T15:15:35.321Z"
  }
]

Create a new pair trading position with order

post

Create a pair trading position with various execution types: MARKET (immediate execution), TRIGGER (conditional execution), TWAP (time-weighted average), or LADDER (multiple ratio levels)

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

slippagenumber · min: 0.001 · max: 0.1Required

Slippage tolerance percentage (0.01 = 1%)

Example: 0.01

executionTypestring · enumRequired

Order execution type

Possible values:

leveragenumber · min: 1 · max: 100Required

Applied leverage

Example: 10

usdValuenumber · min: 1Required

Position size in USD

Example: 1000

triggerValuestringOptional

Required trigger threshold for TRIGGER orders (price, dominance, ratios, etc.)

Example: 45000

triggerTypestring · enumOptional

Trigger type for TRIGGER orders (PRICE, PRICE_RATIO, WEIGHTED_RATIO, BTC_DOM, CROSS_ASSET_PRICE, PREDICTION_MARKET_OUTCOME)

Example: PRICEPossible values:

directionstring · enumOptional

Direction for TRIGGER orders

Possible values:

assetNamestringOptional

Asset to monitor when triggerType is CROSS_ASSET_PRICE

Example: ETH

marketCodestringOptional

Market code to monitor when triggerType is PREDICTION_MARKET_OUTCOME

Example: KALSHI:EVENT_CODE

marketSourcestring · enumOptional

Market source for prediction market orders

Example: KALSHIPossible values:

twapDurationnumberOptional

TWAP duration in minutes (required for TWAP orders)

Example: 120

twapIntervalSecondsnumber · min: 1 · max: 3600Optional

TWAP interval in seconds (time between chunks). Defaults to 30 seconds if not provided.

Example: 30

randomizeExecutionbooleanOptional

Randomize TWAP execution timing

Default: false

referralCodestringOptional

Referral code to be attached to user address if user has no referral code

Example: 0x48656c6c6f20776f726c64210000000000000000000000000000000000000000'

Responses

201

Position order created successfully

application/json

post

/positions

HTTPcURLJavaScriptPython

POST /positions HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 680

{
  "slippage": 0.01,
  "executionType": "SYNC",
  "leverage": 10,
  "usdValue": 1000,
  "longAssets": [
    {
      "asset": "BTC",
      "weight": 0.6
    },
    {
      "asset": "ETH",
      "weight": 0.4
    }
  ],
  "shortAssets": [
    {
      "asset": "SOL",
      "weight": 0.7
    },
    {
      "asset": "AVAX",
      "weight": 0.3
    }
  ],
  "triggerValue": "45000",
  "triggerType": "PRICE",
  "direction": "MORE_THAN",
  "assetName": "ETH",
  "marketCode": "KALSHI:EVENT_CODE",
  "marketSource": "KALSHI",
  "twapDuration": 120,
  "twapIntervalSeconds": 30,
  "randomizeExecution": false,
  "ladderConfig": {
    "ratioStart": 42000,
    "ratioEnd": 48000,
    "numberOfLevels": 5
  },
  "stopLoss": {
    "type": "PERCENTAGE",
    "value": 15
  },
  "takeProfit": {
    "type": "PERCENTAGE",
    "value": 25
  },
  "referralCode": "0x48656c6c6f20776f726c64210000000000000000000000000000000000000000'"
}

201

Position order created successfully

{
  "orderId": "a1b2c3d4e5f67890abcdef1234567891",
  "fills": [
    {
      "coin": "text",
      "px": "text",
      "sz": "text",
      "side": "B",
      "time": 1,
      "dir": "text",
      "fee": "text",
      "builderFee": "text",
      "startPosition": "text",
      "oid": "text",
      "tid": "text",
      "cloid": "text",
      "hash": "text",
      "feeToken": "text",
      "liquidation": {
        "liquidatedUser": "text",
        "markPx": "text",
        "method": "text"
      },
      "closedPnl": {},
      "crossed": {},
      "twapId": {}
    }
  ]
}

Close an entire position

post

Close a position using MARKET (immediate execution), TWAP (time-weighted average), or TRIGGER (conditional trigger-close order) execution type

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

positionIdstring · uuidRequired

Position identifier

Body

application/json

executionTypestring · enumRequired

Type of close order

Possible values:

twapDurationnumberOptional

TWAP duration in minutes - required if executionType is TWAP

Example: 60

twapIntervalSecondsnumberOptional

TWAP interval in seconds (time between close chunks). Defaults to 30 seconds if not provided.

Example: 30

randomizeExecutionbooleanOptional

Randomize TWAP execution times - optional for TWAP orders

Example: true

triggerValuestringOptional

Trigger threshold for TRIGGER close orders

Example: 1.08

triggerTypestring · enumOptional

Trigger type for TRIGGER close orders

Possible values:

directionstring · enumOptional

Direction for TRIGGER close orders

Possible values:

referralCodestringOptional

Referral code to be attached to user address if user has no referral code

Example: 0x48656c6c6f20776f726c64210000000000000000000000000000000000000000'

Responses

200

Position close order created

application/json

orderIdstring · uuidRequired

Unique identifier for the close order

Example: 550e8400-e29b-41d4-a716-446655440003

executionTimestringOptional

Execution time for the order

Example: 2023-12-01T10:00:00.000Z

orderIdsstring[]Optional

Created trigger order identifiers for TRIGGER close requests

chunksSchedulednumberOptional

Number of TWAP chunks scheduled (only for TWAP orders)

Example: 10

post

/positions/{positionId}/close

HTTPcURLJavaScriptPython

POST /positions/{positionId}/close HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 248

{
  "executionType": "MARKET",
  "twapDuration": 60,
  "twapIntervalSeconds": 30,
  "randomizeExecution": true,
  "triggerValue": "1.08",
  "triggerType": "PRICE",
  "direction": "MORE_THAN",
  "referralCode": "0x48656c6c6f20776f726c64210000000000000000000000000000000000000000'"
}

200

Position close order created

{
  "orderId": "550e8400-e29b-41d4-a716-446655440003",
  "executionTime": "2023-12-01T10:00:00.000Z",
  "orderIds": [
    "text"
  ],
  "chunksScheduled": 10
}

Close all open positions

post

Fetches all open positions and closes them sequentially using MARKET or TWAP execution

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

executionTypestring · enumRequired

Type of close order

Possible values:

twapDurationnumberOptional

TWAP duration in minutes - required if executionType is TWAP

Example: 60

twapIntervalSecondsnumberOptional

TWAP interval in seconds (time between close chunks). Defaults to 30 seconds if not provided.

Example: 30

randomizeExecutionbooleanOptional

Randomize TWAP execution times - optional for TWAP orders

Example: true

triggerValuestringOptional

Trigger threshold for TRIGGER close orders

Example: 1.08

triggerTypestring · enumOptional

Trigger type for TRIGGER close orders

Possible values:

directionstring · enumOptional

Direction for TRIGGER close orders

Possible values:

referralCodestringOptional

Referral code to be attached to user address if user has no referral code

Example: 0x48656c6c6f20776f726c64210000000000000000000000000000000000000000'

Responses

200

Close orders created for all positions

application/json

post

/positions/close-all

HTTPcURLJavaScriptPython

POST /positions/close-all HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 248

{
  "executionType": "MARKET",
  "twapDuration": 60,
  "twapIntervalSeconds": 30,
  "randomizeExecution": true,
  "triggerValue": "1.08",
  "triggerType": "PRICE",
  "direction": "MORE_THAN",
  "referralCode": "0x48656c6c6f20776f726c64210000000000000000000000000000000000000000'"
}

200

Close orders created for all positions

{
  "results": [
    {
      "positionId": "text",
      "success": true,
      "orderId": "text",
      "error": "text"
    }
  ]
}

Adjust position size by reducing or increasing by a specified amount

post

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

positionIdstring · uuidRequired

Position identifier

Body

application/json

adjustmentTypestring · enumRequired

Type of position adjustment (reduce or increase)

Default: REDUCEPossible values:

adjustmentSizenumber · min: 1 · max: 100Required

Percentage of position to adjust (1-100%)

Example: 25

executionTypestring · enumRequired

Type of execution for the adjustment

Default: MARKETPossible values:

limitRationumberOptional

Required if executionType is LIMIT

Example: 50000

referralCodestringOptional

Referral code to be attached to user address if user has no referral code

Example: 0x48656c6c6f20776f726c64210000000000000000000000000000000000000000'

Responses

200

Position adjustment order created successfully

application/json

orderIdstring · uuidRequired

Unique identifier for the adjustment order

Example: 550e8400-e29b-41d4-a716-446655440003

statusstringRequired

Status of the adjustment order

Example: SUCCESS

adjustmentTypestring · enumRequired

Type of adjustment that was made

Possible values:

adjustmentSizenumberRequired

Percentage used for position adjustment

Example: 25

newSizenumberRequired

New position size after adjustment

Example: 3.5

executedAtstring · date-timeRequired

Timestamp when the reduction was executed

Example: 2023-07-14T10:30:00Z

post

/positions/{positionId}/adjust

HTTPcURLJavaScriptPython

POST /positions/{positionId}/adjust HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 176

{
  "adjustmentType": "REDUCE",
  "adjustmentSize": 25,
  "executionType": "MARKET",
  "limitRatio": 50000,
  "referralCode": "0x48656c6c6f20776f726c64210000000000000000000000000000000000000000'"
}

200

Position adjustment order created successfully

{
  "orderId": "550e8400-e29b-41d4-a716-446655440003",
  "status": "SUCCESS",
  "adjustmentType": "REDUCE",
  "adjustmentSize": 25,
  "newSize": 3.5,
  "executedAt": "2023-07-14T10:30:00Z"
}

Adjust position to target absolute sizes per asset (advance)

post

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

positionIdstring · uuidRequired

Position identifier

Bodyobject[]

application/json

Responses

200

Advance adjustment executed

application/json

orderIdstringRequired

Order identifier

statusstringRequired

Order status

executedAtstringRequired

Execution timestamp

post

/positions/{positionId}/adjust-advance

HTTPcURLJavaScriptPython

POST /positions/{positionId}/adjust-advance HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 88

[
  {
    "longAssets": [
      {
        "asset": "BTC",
        "size": 0.3
      }
    ],
    "shortAssets": [
      {
        "asset": "BTC",
        "size": 0.3
      }
    ]
  }
]

200

Advance adjustment executed

{
  "orderId": "text",
  "status": "text",
  "executedAt": "text"
}

Adjust leverage for a position

post

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

positionIdstring · uuidRequired

Position identifier

Body

application/json

leveragenumber · min: 1 · max: 100Required

Applied leverage

Example: 10

Responses

200

Leverage updated successfully

application/json

objectOptional

post

/positions/{positionId}/adjust-leverage

HTTPcURLJavaScriptPython

POST /positions/{positionId}/adjust-leverage HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "leverage": 10
}

200

Leverage updated successfully

{}

Preview rebalance plan without executing

post

Computes weight deltas and returns what would be traded, without placing any orders. Use this to preview before calling the execute endpoint.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

positionIdstring · uuidRequired

Position identifier

Body

application/json

Responses

200

Rebalance plan computed successfully

application/json

positionIdstringRequired

Position ID being rebalanced

canExecutebooleanRequired

Whether any asset has a non-skipped trade to execute

post

/positions/{positionId}/rebalance/plan

HTTPcURLJavaScriptPython

POST /positions/{positionId}/rebalance/plan HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "targetWeights": {
    "BTC": 0.6,
    "ETH": 0.4
  }
}

200

Rebalance plan computed successfully

{
  "positionId": "text",
  "assets": [
    {
      "coin": "BTC",
      "side": "long",
      "currentWeight": 0.55,
      "targetWeight": 0.6,
      "currentValue": 5500,
      "targetValue": 6000,
      "deltaValue": 500,
      "currentSize": 0.05,
      "newSize": 0.055,
      "deltaSize": 0.005,
      "skipped": true,
      "skipReason": "text"
    }
  ],
  "canExecute": true
}

Rebalance position assets to target weights

post

Computes weight deltas and adjusts asset sizes to match target weights. Uses existing targetWeight from position if no overrides provided.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

positionIdstring · uuidRequired

Position identifier

Body

application/json

Responses

200

Rebalance executed successfully

application/json

orderIdstringRequired

Rebalance order ID

statusstringRequired

Execution status

Example: EXECUTED

executedAtstringRequired

ISO 8601 timestamp of execution

post

/positions/{positionId}/rebalance

HTTPcURLJavaScriptPython

POST /positions/{positionId}/rebalance HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "targetWeights": {
    "BTC": 0.6,
    "ETH": 0.4
  }
}

200

Rebalance executed successfully

{
  "orderId": "text",
  "status": "EXECUTED",
  "executedAt": "text",
  "plan": {
    "positionId": "text",
    "assets": [
      {
        "coin": "BTC",
        "side": "long",
        "currentWeight": 0.55,
        "targetWeight": 0.6,
        "currentValue": 5500,
        "targetValue": 6000,
        "deltaValue": 500,
        "currentSize": 0.05,
        "newSize": 0.055,
        "deltaSize": 0.005,
        "skipped": true,
        "skipReason": "text"
      }
    ],
    "canExecute": true
  }
}

Update stop loss and take profit values for a position

put

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

positionIdstring · uuidRequired

Position identifier

Body

application/json

Responses

200

Risk parameters updated successfully

application/json

positionIdstring · uuidRequired

Position identifier

Example: 550e8400-e29b-41d4-a716-446655440000

updatedAtstring · date-timeRequired

Update timestamp

Example: 2023-07-14T10:35:00Z

put

/positions/{positionId}/riskParameters

HTTPcURLJavaScriptPython

PUT /positions/{positionId}/riskParameters HTTP/1.1
Host: hl-v2.pearprotocol.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 239

{
  "stopLoss": {
    "type": "PERCENTAGE",
    "value": 15,
    "isTrailing": false,
    "trailingDeltaValue": 5,
    "trailingActivationValue": 50000
  },
  "takeProfit": {
    "type": "PERCENTAGE",
    "value": 15,
    "isTrailing": false,
    "trailingDeltaValue": 5,
    "trailingActivationValue": 50000
  }
}

200

Risk parameters updated successfully

{
  "positionId": "550e8400-e29b-41d4-a716-446655440000",
  "stopLoss": {
    "type": "PERCENTAGE",
    "value": 15,
    "isTrailing": false,
    "trailingDeltaValue": 5,
    "trailingActivationValue": 50000
  },
  "takeProfit": {
    "type": "PERCENTAGE",
    "value": 15,
    "isTrailing": false,
    "trailingDeltaValue": 5,
    "trailingActivationValue": 50000
  },
  "updatedAt": "2023-07-14T10:35:00Z"
}