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

pearExecutionFlagstringRequired

Pear execution flag

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": "text",
    "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,
        "initialWeight": 0.5,
        "fundingPaid": -3.25
      }
    ],
    "shortAssets": [
      {
        "coin": "BTC",
        "entryPrice": 50000,
        "actualSize": 0.1,
        "leverage": 5,
        "marginUsed": 5000,
        "positionValue": 5200,
        "unrealizedPnl": 200,
        "entryPositionValue": 5000,
        "initialWeight": 0.5,
        "fundingPaid": -3.25
      }
    ],
    "createdAt": "2026-02-23T20:12:34.425Z",
    "updatedAt": "2026-02-23T20:12:34.425Z"
  }
]

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

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

stopLossobject · nullableOptional

Stop loss trigger. PERCENTAGE: % change vs entry; DOLLAR: fixed USD change; POSITION_VALUE: % change of position value.

Example: {"type":"PERCENTAGE","value":15}

takeProfitobject · nullableOptional

Take profit trigger. PERCENTAGE: % change vs entry; DOLLAR: fixed USD change; POSITION_VALUE: % change of position value.

Example: {"type":"PERCENTAGE","value":25}

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: 656

{
  "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",
  "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": []
}

Close an entire position

post

Close a position using MARKET (immediate execution) or TWAP (time-weighted average) 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

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

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: 180

{
  "executionType": "MARKET",
  "twapDuration": 60,
  "twapIntervalSeconds": 30,
  "randomizeExecution": true,
  "referralCode": "0x48656c6c6f20776f726c64210000000000000000000000000000000000000000'"
}

200

Position close order created

{
  "orderId": "550e8400-e29b-41d4-a716-446655440003",
  "executionTime": "2023-12-01T10:00:00.000Z",
  "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

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: 180

{
  "executionType": "MARKET",
  "twapDuration": 60,
  "twapIntervalSeconds": 30,
  "randomizeExecution": true,
  "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

Bodystring[]

application/json

string[]Optional

Responses

200

Advance adjustment executed

application/json

objectOptional

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: 8

[
  "text"
]

200

Advance adjustment executed

{}

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

{}

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"
}