POST
/
api
/
newposition
curl --request POST \
  --url https://unidexv4-api-production.up.railway.app/api/newposition \
  --header 'Content-Type: application/json' \
  --data '{
  "pair": 50,
  "isLong": true,
  "orderType": "market",
  "margin": 123,
  "size": 123,
  "maxAcceptablePrice": 123,
  "slippagePercent": 123,
  "limitPrice": 123,
  "stopMarketPrice": 123,
  "takeProfit": 123,
  "stopLoss": 123,
  "takeProfitClosePercent": 123,
  "stopLossClosePercent": 123,
  "userAddress": "<string>",
  "refer": "<string>"
}'
{
  "calldata": "<string>",
  "vaultAddress": "<string>",
  "requiredGasFee": "<string>",
  "insufficientBalance": true,
  "error": "<string>"
}

Overview

The New Position endpoint allows you to create trading positions with various order types, including market orders, limit orders, stop-market orders, and stop-limit orders. Each position can be configured with optional take profit and stop loss orders.

Request Body

pair
number
required

Trading pair ID (number between 1 and 100)

isLong
boolean
required

Position direction (true for long, false for short)

orderType
string
required

Type of order. Must be one of:

  • market: Market order at current price
  • limit: Limit order at specified price
  • stop-market: Market order triggered at stop price
  • stop-limit: Limit order triggered at stop price
margin
number
required

Margin amount in base currency

size
number
required

Position size in base currency

maxAcceptablePrice
number

Required for market orders. Maximum price willing to accept

slippagePercent
number

Required for market orders. Allowed slippage in basis points (100 = 1%)

limitPrice
number

Required for limit and stop-limit orders. Price at which to execute

stopMarketPrice
number

Required for stop-market and stop-limit orders. Price at which to trigger

takeProfit
number

Optional take profit price in base currency

stopLoss
number

Optional stop loss price in base currency

takeProfitClosePercent
number

Required if takeProfit is set. Percentage to close at take profit (in basis points, 10000 = 100%)

stopLossClosePercent
number

Required if stopLoss is set. Percentage to close at stop loss (in basis points, 10000 = 100%)

userAddress
string
required

Ethereum address of the user creating the position

refer
string

Optional referral address (defaults to zero address)

Required Parameters by Order Type

Market Orders

  • maxAcceptablePrice
  • slippagePercent
  • margin
  • size

Limit Orders

  • limitPrice
  • margin
  • size

Stop-Market Orders

  • stopMarketPrice
  • margin
  • size

Stop-Limit Orders

  • limitPrice
  • stopMarketPrice
  • margin
  • size

Response Fields

calldata
string

Encoded function call data for the transaction

vaultAddress
string

Address of the vault contract

insufficientBalance
boolean

Indicates if user has insufficient balance

requiredGasFee
string

Required gas fee for the transaction

error
string

Error message if balance is insufficient (only present if there’s an error)

Example Usage

curl -X POST "https://unidexv4-api-production.up.railway.app/api/newposition" \
  -H "Content-Type: application/json" \
  -d '{
    "pair": 1,
    "isLong": true,
    "orderType": "market",
    "maxAcceptablePrice": 67000,
    "slippagePercent": 100,
    "margin": 20,
    "size": 30,
    "takeProfit": 69000,
    "stopLoss": 61000,
    "takeProfitClosePercent": 10000,
    "stopLossClosePercent": 10000,
    "userAddress": "0x1234567890123456789012345678901234567890"
}'

Example Response

{
  "calldata": "0x4d59524546455252414c434f4445000000000000000000000000000000000000",
  "vaultAddress": "0xe3ca135782e4a17aFb31a63ee3b15351C891A1A2",
  "insufficientBalance": false,
  "requiredGasFee": "0.0012"
}

Error Responses

The endpoint will return a 400 status code with an error message for:

  • Invalid pair value (must be between 1 and 100)
  • Invalid or missing isLong boolean value
  • Invalid orderType value
  • Missing required parameters for the specified order type
  • Missing close percentages when take profit or stop loss is specified

A 500 status code will be returned for server-side errors.

Body

application/json

Response

200
application/json
Successful response

The response is of type object.