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.