PerpsHub TP/SL Implementation

Overview

The stop-loss/take-profit (SL/TP) system allows users to automatically close positions when the market price reaches specified trigger levels. The system continuously monitors mark prices and executes closes when conditions are met.

Base URL Pattern: /v1/:symmId/:multiaccount

All endpoints require the following path parameters:

• symmId: Network/chain identifier (e.g., '56a', '5000a', '42161a', '8453a', etc.)

• multiaccount: Ethereum address of the multi-account contract

---

Endpoints

1. Create Stop Loss / Take Profit

Create or update a stop-loss and/or take-profit order for a specific position.

Endpoint:

• POST /v1/:symmId/:multiaccount/stop_loss

• POST /v1/:symmId/:multiaccount/stop-loss (kebab-case alternative)

Authentication: Required (Bearer token)

Request Body:

{
  userAddress: string        // Ethereum address of the user (0x...)
  accountAddress: string     // Ethereum address of the account/partyA (0x...)
  positionSide: 0 | 1       // 0 = LONG, 1 = SHORT
  symbolId: number          // Numeric symbol identifier
  requestedPrice: string    // Requested open price (decimal string)
  quoteId: number           // Quote ID (positive for filled trades, negative for pending instant opens)
  tpPrice: string           // Take profit trigger price (decimal string, can be empty)
  slPrice: string           // Stop loss trigger price (decimal string, can be empty)
  timestamp: number         // Request timestamp in milliseconds
}

Validation Rules:

• At least one of tpPrice or slPrice must be provided (non-empty)

• tpPrice and slPrice cannot be equal

• For LONG positions:

  • tpPrice must be ABOVE the current/estimated mark price

  • slPrice must be BELOW the current/estimated mark price

• For SHORT positions:

  • tpPrice must be BELOW the current/estimated mark price

  • slPrice must be ABOVE the current/estimated mark price

Success Response (200 OK):

{
  "success": true,
  "statusMessage": "Stoploss created",
  "data": {
    "success": true,
    "statusMessage": "Stoploss created"
  }
}

Error Responses:

400 Bad Request:

{
  "error": "Stoploss request must have either TP or SL"
}

{
  "error": "Stoploss request cannot have TP and SL equal"
}

{
  "error": "Take profit price is invalid"
}

{
  "error": "Stop loss price is invalid"
}

{
  "error": "Stop loss already exists for this trade"
}

{
  "error": "Unsupported symbol"
}

404 Not Found:

{
  "error": "Trade not found"
}

Notes:

• If a stop-loss already exists for the trade in PENDING status, the request will be rejected

• The system validates prices against the current mark price (for opened positions) or estimated fill price (for pending instant opens)

• Prices are validated with slippage considerations

Example:

curl -X POST \
  https://api.example.com/v1/42161a/0x1234...5678/stop-loss \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0xabcd...ef01",
    "accountAddress": "0x1234...5678",
    "positionSide": 0,
    "symbolId": 123,
    "requestedPrice": "50000.5",
    "quoteId": 12345,
    "tpPrice": "55000",
    "slPrice": "48000",
    "timestamp": 1234567890000
  }'

---

2. List Stop Losses / Take Profits

Retrieve stop-loss/take-profit orders for multiple quote IDs.

Endpoint:

• POST /v1/:symmId/:multiaccount/list_sl

• POST /v1/:symmId/:multiaccount/list-sl-tp (kebab-case alternative)

Authentication: Not required

Request Body:

{
  quoteIds: number[]  // Array of quote IDs (minimum 1 item)
}

Success Response (200 OK):

{
  "success": true,
  "statusMessage": "Stoplosses listed",
  "data": {
    "statusMessage": "Stoplosses listed",
    "success": true,
    "data": {
      "12345": {
        "symmId": "42161a",
        "quoteId": 12345,
        "userAddress": "0xabcd...ef01",
        "affiliate": "0x1234...5678",
        "partyA": "0x9876...5432",
        "tpPrice": "55000",
        "slPrice": "48000",
        "timestamp": 1234567890000,
        "status": "pending",
        "positionSide": 0,
        "lastCheckedAt": 1234567890000,
        "symbolName": "BTCUSDT"
      },
      "67890": {
        "symmId": "42161a",
        "quoteId": 67890,
        "userAddress": "0xabcd...ef01",
        "affiliate": "0x1234...5678",
        "partyA": "0x9876...5432",
        "tpPrice": null,
        "slPrice": "3200",
        "timestamp": 1234567891000,
        "status": "pending",
        "positionSide": 0,
        "lastCheckedAt": 1234567891000,
        "symbolName": "ETHUSDT"
      }
    }
  }
}

Response Fields:

• symmId: Network identifier

• quoteId: Quote/trade identifier

• userAddress: User's address

• affiliate: Affiliate/multiaccount address

• partyA: Account address (partyA)

• tpPrice: Take profit trigger price (null if not set)

• slPrice: Stop loss trigger price (null if not set)

• timestamp: Creation timestamp

• status: Order status ("pending", "processing", "executed", "cancelled")

• positionSide: 0 = LONG, 1 = SHORT

• lastCheckedAt: Last time the order was checked by the system

• symbolName: Trading symbol (e.g., "BTCUSDT")

Error Response (400 Bad Request):

{
  "error": "Error message"
}

Example:

curl -X POST \
  https://api.example.com/v1/42161a/0x1234...5678/list-sl-tp \
  -H "Content-Type: application/json" \
  -d '{
    "quoteIds": [12345, 67890, 11111]
  }'

---

3. Cancel Stop Loss / Take Profit

Cancel the stop-loss and/or take-profit for a specific quote.

Endpoint:

• POST /v1/:symmId/:multiaccount/cancel_sl

• POST /v1/:symmId/:multiaccount/cancel-sl-tp (kebab-case alternative)

Authentication: Required (Bearer token)

Request Body:

{
  quoteId: number         // Quote ID to cancel
  cancelSl?: boolean     // Whether to cancel stop loss (optional, default: false)
  cancelTp?: boolean     // Whether to cancel take profit (optional, default: false)
}

Validation Rules:

• At least one of cancelSl or cancelTp must be true

• The stop-loss order must exist for the given quote

• The stop-loss order must be in PENDING status (cannot cancel processing/executed orders)

Success Response (200 OK):

When canceling both:

{
  "success": true,
  "statusMessage": "Stop loss and take profit cancelled",
  "data": {
    "success": true,
    "statusMessage": "Stop loss and take profit cancelled"
  }
}

When canceling only stop loss:

{
  "success": true,
  "statusMessage": "Stop loss cancelled",
  "data": {
    "success": true,
    "statusMessage": "Stop loss cancelled"
  }
}

When canceling only take profit:

{
  "success": true,
  "statusMessage": "Take profit cancelled",
  "data": {
    "success": true,
    "statusMessage": "Take profit cancelled"
  }
}

Error Responses:

400 Bad Request:

{
  "error": "Must cancel at least one of SL or TP"
}

{
  "error": "Can only cancel pending stop loss orders"
}

{
  "error": "Error while cancelling stop loss"
}

404 Not Found:

{
  "error": "Stop loss not found for this quote"
}

Notes:

• If both cancelSl and cancelTp are true (or if canceling the only remaining one), the entire stop-loss document is removed

• If only one is canceled and the other remains, the document is updated with the remaining value

• Partial cancellation is supported: you can cancel just SL or just TP while keeping the other active

Example:

Cancel both SL and TP:

curl -X POST \
  https://api.example.com/v1/42161a/0x1234...5678/cancel-sl-tp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": 12345,
    "cancelSl": true,
    "cancelTp": true
  }'

Cancel only stop loss:

curl -X POST \
  https://api.example.com/v1/42161a/0x1234...5678/cancel-sl-tp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": 12345,
    "cancelSl": true,
    "cancelTp": false
  }'

---

Stop Loss States

Status	Description
PENDING	Order is active and being monitored
PROCESSING	Trigger conditions met, execution in progress
EXECUTED	Order successfully executed
CANCELLED	Order cancelled by user

Authentication

Endpoints marked as requiring authentication must include a Bearer token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

To obtain an access token, use the login endpoints:

• POST /v1/:symmId/:multiaccount/login (for EVM wallets)

• POST /v1/:symmId/:multiaccount/tac-login (for TON wallets)

---

Common Error Codes

HTTP Status	Error Message	Description
400	Invalid symmId	The symmId path parameter is not valid
400	Validation error	Request body validation failed
401	Invalid or missing credentials	Authentication token is missing or invalid
404	Trade not found	The specified quote ID does not exist
404	Stop loss not found	No stop-loss order exists for the quote
500	Internal server error	Unexpected server error