Create New Position - Starter Kit

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

pair

integer

required

Trading pair ID

Required range: 1 <= x <= 100

isLong

boolean

required

Position direction

orderType

enum<string>

required

Type of order

Available options:

market,

limit,

stop-market,

stop-limit

margin

number

required

Margin amount in base currency

size

number

required

Position size in base currency

userAddress

string

required

Ethereum address of the user

maxAcceptablePrice

number

Maximum price willing to accept (for market orders)

slippagePercent

number

Allowed slippage in basis points (for market orders)

limitPrice

number

Limit price (for limit and stop-limit orders)

stopMarketPrice

number

Stop price (for stop-market and stop-limit orders)

takeProfit

number

Take profit price

stopLoss

number

Stop loss price

takeProfitClosePercent

number

Percentage to close at take profit (in basis points)

stopLossClosePercent

number

Percentage to close at stop loss (in basis points)

refer

string

Optional referral address

Response

200

application/json

Successful response

calldata

string

required

Encoded function call data

vaultAddress

string

required

Address of the vault contract

requiredGasFee

string

Required gas fee for the transaction

insufficientBalance

boolean

Indicates if user has insufficient balance

error

string

Error message if balance is insufficient

Get User Positions Close Position

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

API Reference

​Overview

​Request Body

​Required Parameters by Order Type

​Market Orders

​Limit Orders

​Stop-Market Orders

​Stop-Limit Orders

​Response Fields

​Example Usage

​Example Response

​Error Responses

Body

Response

Overview

Request Body

Required Parameters by Order Type

Market Orders

Limit Orders

Stop-Market Orders

Stop-Limit Orders

Response Fields

Example Usage

Example Response

Error Responses