Skip to main content

Private HTTP API

Authentication

Please refer to the Private endpoint authentication section.

Endpoints

Register Account

Register Account

POST /v1/account

Parameters:

ParameterTypeMandatoryDescription
accountSTRINGYESEthereum address

Success Response

{
"address": "0x0000000000000000000000000000000000000003",
"createdAt": 1655774600530,
}

Error Response

{
"code": 2018,
"codeText": "Duplicated account",
"message": "Duplicated"
}

Get Account

GET /v1/account

Parameters:

ParameterTypeMandatoryDescription
accountSTRINGYESEthereum address

Success Response

{
"address": "0x0000000000000000000000000000000000000003",
"createdAt": 1655774600530,
}

Error Response

{
"code": 1110,
"codeText": "Invalid account address",
"message": "Invalid account address"
}

Orders Creation

There are two ways to place an order,

  1. The first way is to directly interact with the api to construct the order without understanding the order data structure in the contract.

    1. Pass in the parameters to call the Build Unsigned Order API, and get the orderHash and info.
    2. Sign the orderHash to get order signature, use the same parameters as when calling the Build Unsigned Order API in the previous step, along with the returned info field and the order signature to request the New Order API.
  2. The second way is to piece together the order data structure in the contract locally, then calculate the hash of the order locally and sign it, and then directly call the New Order API.

    Golang code example to build an order locally
    package main

    import (
    "encoding/binary"
    "fmt"
    "math/big"
    "math/rand"
    "time"

    "github.com/ethereum/go-ethereum/accounts/abi"
    "github.com/ethereum/go-ethereum/common"
    "github.com/ethereum/go-ethereum/common/hexutil"
    "github.com/ethereum/go-ethereum/crypto"
    "github.com/shopspring/decimal"
    )

    const (
    // The two values can be found in `/$version/exchangeInfo`
    domainName = "JOJO"
    domainVersion = "1"
    )

    var (
    orderTypeArgument abi.Arguments

    EIP712_DOMAIN_TYPEHASH []byte
    EIP712_ORDER_TYPE []byte
    EIP712_DOMAIN_SEPARATOR []byte
    VerifyingContract string
    )

    // JOJOProtocolOrder is an auto generated low-level Go binding around an user-defined struct.
    type JOJOProtocolOrder struct {
    Perp common.Address
    Signer common.Address
    PaperAmount *big.Int
    CreditAmount *big.Int
    Info [32]byte
    }

    func init() {
    rand.Seed(time.Now().UTC().UnixMilli())

    orderType, _ := abi.NewType("tuple", "struct Types.Order", []abi.ArgumentMarshaling{
    {
    Name: "perp",
    Type: "address",
    InternalType: "address",
    },
    {
    InternalType: "address",
    Name: "signer",
    Type: "address",
    },
    {
    InternalType: "int128",
    Name: "paperAmount",
    Type: "int128",
    },
    {
    InternalType: "int128",
    Name: "creditAmount",
    Type: "int128",
    },
    {
    InternalType: "bytes32",
    Name: "info",
    Type: "bytes32",
    },
    })

    orderTypeArgument = abi.Arguments{{Type: orderType}}
    }

    func getEIP712DomainSeparator(name string, version string, cid int64, contractAddress string) []byte {
    return crypto.Keccak256(
    EIP712_DOMAIN_TYPEHASH,
    crypto.Keccak256([]byte(name)),
    crypto.Keccak256([]byte(version)),
    common.BigToHash(big.NewInt(int64(cid))).Bytes(),
    common.HexToAddress(contractAddress).Hash().Bytes(),
    )
    }

    func getEIP712MessageHash(message []byte) []byte {
    return crypto.Keccak256(
    []byte{'\x19', '\x01'},
    EIP712_DOMAIN_SEPARATOR,
    message,
    )
    }

    func InitEIP712(chainId int64, verifyingContract string) {
    EIP712_DOMAIN_TYPEHASH = crypto.Keccak256([]byte(`EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)`))
    EIP712_DOMAIN_SEPARATOR = getEIP712DomainSeparator(domainName, domainVersion, chainId, verifyingContract)
    EIP712_ORDER_TYPE = crypto.Keccak256([]byte(`Order(address perp,address signer,int128 paperAmount,int128 creditAmount,bytes32 info)`))
    VerifyingContract = common.HexToAddress(verifyingContract).String()
    }

    func GetOrderHash(order *JOJOProtocolOrder) []byte {
    bytes, err := orderTypeArgument.Pack(*order)

    if err != nil {
    panic(err)
    }

    return getEIP712MessageHash(crypto.Keccak256(EIP712_ORDER_TYPE, bytes))
    }

    func PackProtocolOrderInfo(makerFeeRate, takerFeeRate *big.Int, expiration, nonce uint64) [32]byte {
    var buf [32]byte
    binary.BigEndian.PutUint64(buf[:], uint64(makerFeeRate.Int64()))
    binary.BigEndian.PutUint64(buf[8:], uint64(takerFeeRate.Int64()))
    binary.BigEndian.PutUint64(buf[16:], expiration)
    binary.BigEndian.PutUint64(buf[24:], nonce)
    return buf
    }

    func main() {
    // ========= Step 1: Init EIP712 ==========
    // This step only needs to be done once, the purpose is to obtain the correct necessary parameters for generating the order hash.
    // The parameters `verifyingContract` and `chainId` can be found in `/v1/exchangeInfo` API endpoint.
    // After executing the following line of code, you can check whether the calculation is correct by comparing the local variables with prefix `EIP712_` related to the ones in /v1/exchangeInfo.
    InitEIP712(97, "0xCA5c790268C06fa2Ed8850023Ac85EA55E1a7C24")

    // ========= Step 2: Build Order ==========
    // 1. The perp should be the blockchain address of the market, which can be found in `/v1/exchangeInfo` API endpoint.
    // 2. PaperAmount should be the amount of base asset with 18 decimals. The decimal can be found in the `/v1/exchangeInfo` API at jsontpath=".dealerInfo.paperDecimals"
    // 3. CreditAmount should be the amount of quote asset you want to pay/receive for trading the above PaperAmount base assets. The decimal can be found in the `/v1/exchangeInfo` API at jsontpath=".dealerInfo.creditDecimals"
    // 4. Signer should be the address of the account that signs the order.
    // 5. Buying or selling is indicated by the symbols of the numbers. If it is `BUY`, then PaperAmount is positive and CreditAmount is negative. vice versa.
    // 6. The order info is a 32-byte array, which is the concatenation of the following 4 fields:
    // 1) makerFeeRate: the fee rate of the maker, with 18 decimals
    // 2) takerFeeRate: the fee rate of the taker, with 18 decimals
    // 3) expiration: the expiration time of the order, in seconds. If the timeInForce is GTT, the expiration time must be greater than 1 minute and less than 7 days, which needs to be consistent with the `expiration` parameter, otherwise the expiration time must be greater than 10 years.
    // 4) nonce: a random number (uint64)
    // Note: When constructing the field of Info, unless there is a special market maker agreement with JOJO, please fill in `makerFeeRate` and `takerFeeRate` according to the market fee rate that returned in `/v1/exchangeInfo`. Orders that do not match the fee rates will be rejected.
    // 7. Please fill in `creditDecimals` according to the `creditDecimals` that returned in `/v1/exchangeInfo`.

    // Example: Buy 1 BTC at price 30000 USDT

    perp := common.HexToAddress("0x2f648F867B98CbCBD18B47D6D4668F8378420392")
    signer := common.HexToAddress("0x1111111111111111111111111111111111111111")
    amount := "1"
    price := "30000"
    side := "BUY"
    makerFee := "0.0001"
    takerFee := "0.0005"
    expiredAt := time.Now().Add(time.Hour * 24 * 365 * 10).Unix()
    nonce := rand.Uint64()
    creditDecimals := int32(6)

    var (
    paperAmount decimal.Decimal
    creditAmount decimal.Decimal
    )

    if side == "BUY" {
    paperAmount = decimal.RequireFromString(amount).Shift(18)
    creditAmount = decimal.RequireFromString(price).Mul(decimal.RequireFromString(amount)).Shift(creditDecimals).Neg()
    } else {
    paperAmount = decimal.RequireFromString(amount).Shift(18).Neg()
    creditAmount = decimal.RequireFromString(price).Mul(decimal.RequireFromString(amount)).Shift(creditDecimals).Floor()
    }

    order := &JOJOProtocolOrder{
    Perp: perp,
    PaperAmount: paperAmount.BigInt(),
    CreditAmount: creditAmount.BigInt(),
    Signer: signer,
    }

    order.Info = PackProtocolOrderInfo(
    decimal.RequireFromString(makerFee).Shift(18).BigInt(),
    decimal.RequireFromString(takerFee).Shift(18).BigInt(),
    uint64(expiredAt),
    nonce,
    )

    // ======== Step 3: Get Order Hash ==========
    orderHash := GetOrderHash(order)
    fmt.Printf("%s\n", hexutil.Encode(orderHash))

    // At this point, you have locally built an order that can be used for signing, thus eliminating the need to call `/$version/order/build` API.
    }

Build Unsigned Order

This API will return a JOJO unsigned order data structure based on the incoming order parameter. Then you need to sign with the private key to get the signature of the order. This signature is a required parameter in the New Order API.

If you are familiar with how to construct a JOJO unsigned order, then you can generate and sign the order structure locally without calling this API.

POST /v1/order/build

Parameters:

ParameterTypeMandatoryDescription
marketIdSTRINGYESMarket id
sideSTRINGYESBUY or SELL.
orderTypeSTRINGYESMARKET, LIMIT
amountSTRINGYESAmount of the order, in base asset (i.e. an BTC-USDC position of size 1 represents 1 ETH).
priceSTRINGYESWorst accepted price of the base asset.
timeInForceSTRINGYESOne of GTC (Good til cancel), FOK(Fill or kill), IOC (Immediate or cancel) or GTT (Good Til Time). This will default to GTC.
expirationLONGNOOnly GTT (Good Til Time) supports expiration time, and the expiration time must be greater than 1 minute and less than 7 days.

Success Response

{
"order": {
"perp": "0x00De48310d77A4d56aa400248b0B1613508f5B73",
"signer": "0x0000000000000000000000000000000000000001",
"sender": "0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf",
"paperAmount": "-12000000000000000000",
"creditAmount": "504000000",
"info": "0x00005af3107a40000001c6bf52634000000001818bbb69cd145ef7300aa9f59b"
},
"orderHash": "0x7997032c4d8f341e97c5a9f15d1bf4aee7d117f196cbb0473705beca4a9bd774",
"packedOrder": "0x00000000000000000000000000de48310d77a4d56aa400248b0b1613508f5b7300000000000000000000000000000000000000000000000000000000000000010000000000000000000000007e5f4552091a69125d5dfcb7b8c2659029395bdfffffffffffffffffffffffffffffffffffffffffffffffff59776f9427500000000000000000000000000000000000000000000000000000000000001e0a6e0000005af3107a40000001c6bf52634000000001818bbb69cd145ef7300aa9f59b"
"gasFeeQuotation":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJldGhJbmRleFByaWNlIjoiMTkwMC44MjcxNjY5NCIsImV4cGlyYXRpb24iOjE2ODU4Njc4OTEsImdhc0ZlZU9mZnNldCI6IjAiLCJnYXNMaW1pdCI6IjI5NjU5NC43ODI2MDg3IiwiZ2FzUHJpY2UiOiIxMDAwMDAwMDAiLCJtYWtlckZlZVJhdGUiOiIwLjAwMDIiLCJ0YWtlckZlZVJhdGUiOiIwLjAwMDcifQ.CifagCb5tYcQr4v5h3ZJyc0duY4InwQacgA5BZMYRUA"
}

Error Response

{
"code": 1112,
"codeText": "Invalid market id",
"message": "Invalid market id"
}

New Order

Create a new order.

POST /v1/order

Parameters:

ParameterTypeMandatoryDescription
marketIdSTRINGYESMarket id
sideSTRINGYESBUY or SELL.
orderTypeSTRINGYESMARKET, LIMIT
amountSTRINGYESAmount of the order, in base asset (i.e. an BTC-USDC position of size 1 represents 1 ETH).
priceSTRINGYESWorst accepted price of the base asset.
timeInForceSTRINGYESOne of GTC (Good til cancel), FOK(Fill or kill), IOC (Immediate or cancel) or GTT (Good Til Time). This will default to GTC.
orderSignatureSTRINGYESSignature for the order, Sign the orderHash returned in the build order.
infoSTRINGYESInfo returned in buildOrder or the one built locally. If the timeInForce is GTT and the info is built locally, the expiration time must be greater than 1 minute and less than 7 days, which needs to be consistent with the expiration parameter, otherwise the expiration time must be greater than 10 years.
expirationLONGNOOnly GTT (Good Til Time) supports expiration time, and the expiration time must be greater than 1 minute and less than 7 days.
gasFeeQuotationSTRINGNOWhen the order amount is smaller than waiveGasFeeMinimumAmount of /v1/exchangeInfo api, it needs to be passed to the field (from build order api response)

Signature example

privateKey: "0000000000000000000000000000000000000000000000000000000000000001"
orderHash: "0x1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac8"
expectedSignature: "0x433ec3d37e4f1253df15e2dea412fed8e915737730f74b3dfb1353268f932ef5557c9158e0b34bce39de28d11797b42e9b1acb2749230885fe075aedc3e491a41b"
The golang code of the above example
package main

import (
"log"

"github.com/ethereum/go-ethereum/common/hexutil"
"github.com/ethereum/go-ethereum/crypto"
)

func OrderSignatureExample() {
privateKey, err := crypto.HexToECDSA("0000000000000000000000000000000000000000000000000000000000000001") // private key of the account that created the order

if err != nil {
log.Fatal(err)
}

orderHash := hexutil.MustDecode("0x1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac8") // the orderHash

signature, err := crypto.Sign(orderHash, privateKey)

if err != nil {
log.Fatal(err)
}

if signature[64] == 1 {
signature[64] = 28
} else if signature[64] == 0 {
signature[64] = 27
}

if hexutil.Encode(signature) != "0x433ec3d37e4f1253df15e2dea412fed8e915737730f74b3dfb1353268f932ef5557c9158e0b34bce39de28d11797b42e9b1acb2749230885fe075aedc3e491a41b" {
log.Fatal("Signature is not correct")
}

log.Info("Signature is correct")
}

func main() {
OrderSignatureExample()
}

Success Response

Please note that the order return information here cannot be used as trades results. If you need to follow the subsequent changes of the order in real time, such as a trade, you need to connect to the account stream of the websocket.

{
"id": 57262766,
"account": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"marketId": "btcusdc",
"side": "BUY",
"price": "21000",
"tif": "GTC",
"type": "LIMIT",
"amount": "0.1",
"availableAmount": "0.1",
"filledAmount": "0",
"canceledAmount": "0",
"pendingAmount": "0",
"expiredAmount": "0",
"failedAmount": "0",
"json": {
"perp": "0x0eC7f726E7e64aB93dE3AA9d238684d99262c53f",
"signer": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"sender": "0x7777405dB28BcAc40F6FD2AABc62751384aAD38c",
"paperAmount": "100000000000000000",
"creditAmount": "-2100000000",
"info": "0x00005af3107a40000001c6bf5263400000000181911d2837a5001a5c5e2a75b6"
},
"hash": "0x34f88e38ebdca6d3df246c92673117008deb803a61c3c30f79df6efdebbd5aa5",
"createdAt": 1655997024353,
"status": "NEW",
"trades": null,
"expiration": 0
}

Error Response

{
"code": 1012,
"codeText": "Invalid signature",
"message": "Invalid request signature (0000)"
}

Orders Deletion

Cancel An Order

DELETE /v1/order

Parameters:

ParameterTypeMandatoryDescription
marketIdSTRINGYESMarket id
orderIdINTEGERYESOrder Id

Success Response

Nothing will be returned if the order is successfully canceled. The http status code is 204.

Error Response

{
"code": 2011,
"codeText": "No such order",
"message": "No such order"
}

Cancel All Orders

DELETE /v1/allOpenOrders

Parameters:

ParameterTypeMandatoryDescription
marketIdSTRINGNOMarket id. If no pass marketId, will cancel all open orders of all markets.

Response

Nothing will be returned if the orders are successfully canceled. The http status code is 204.

View Orders

Get History Orders

History orders refer to orders whose type is not NEW, in other words, those orders that are no longer active, whose status has been determined and will not change.

GET /v1/historyOrders

Parameters:

ParameterTypeMandatoryDescription
marketIdSTRINGYESMarket id
startTimeINTEGERNOTimestamp millisecond
endTimeINTEGERNOTimestamp millisecond
limitINTEGERNODefault is 100, maximum is 500

Success Response

[
{
"id": 57262764,
"account": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"marketId": "btcusdc",
"side": "BUY",
"price": "21000",
"tif": "GTC",
"averagePrice": "21010.5",
"type": "LIMIT",
"amount": "0.1",
"availableAmount": "0",
"filledAmount": "0.1",
"canceledAmount": "0",
"pendingAmount": "0",
"expiredAmount": "0",
"failedAmount": "0",
"json": {
"perp": "0x0eC7f726E7e64aB93dE3AA9d238684d99262c53f",
"signer": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"sender": "0x7777405dB28BcAc40F6FD2AABc62751384aAD38c",
"paperAmount": "100000000000000000",
"creditAmount": "-2100000000",
"info": "0x00005af3107a40000001c6bf526340000000018190c54e4c5f715ac6384cb0fa"
},
"hash": "0xaf508948c9fed3b3eb6746b23e5817b743db31f5ba1b6ad09ae91f4f51e094b4",
"createdAt": 1655991301591,
"status": "FILLED",
"expiration": 0
}
]

Error Response

{
"code": 1112,
"codeText": "Invalid market id",
"message": "Invalid market id"
}

Get A History Order By ID

Only history order is available in this API. Open order will not be returned.

GET /v1/order

Parameters:

ParameterTypeMandatoryDescription
marketIdSTRINGYESMarket id.
orderIdINTEGERYESOrder Id

Success Response

{
"id": 57262765,
"account": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"marketId": "btcusdc",
"side": "BUY",
"price": "21000",
"tif": "GTC",
"averagePrice": "21010.37826087",
"type": "LIMIT",
"amount": "1",
"availableAmount": "0.31",
"filledAmount": "0.69",
"canceledAmount": "0",
"pendingAmount": "0",
"expiredAmount": "0",
"failedAmount": "0",
"json": {
"perp": "0x0eC7f726E7e64aB93dE3AA9d238684d99262c53f",
"signer": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"sender": "0x7777405dB28BcAc40F6FD2AABc62751384aAD38c",
"paperAmount": "1000000000000000000",
"creditAmount": "-21000000000",
"info": "0x00005af3107a40000001c6bf5263400000000181911c36d81cdca47ffda96bbb"
},
"hash": "0xba6f1df5d639e8a192bc4d40bc8f181404c5b1ffe149d9ca9b907008675716ab",
"createdAt": 1655996973522,
"status": "PARTIAL_FILLED",
"trades": null,
"expiration": 0
}

Get An Open Order

GET /v1/openOrder

Parameters:

ParameterTypeMandatoryDescription
marketIdSTRINGNOMarket id
orderIdINTEGERNOOrder id

Success Response

{
"id": 57262765,
"account": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"marketId": "btcusdc",
"side": "BUY",
"price": "21000",
"tif": "GTC",
"averagePrice": "21010.37826087",
"type": "LIMIT",
"amount": "1",
"availableAmount": "0.31",
"filledAmount": "0.69",
"canceledAmount": "0",
"pendingAmount": "0",
"expiredAmount": "0",
"failedAmount": "0",
"json": {
"perp": "0x0eC7f726E7e64aB93dE3AA9d238684d99262c53f",
"signer": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"sender": "0x7777405dB28BcAc40F6FD2AABc62751384aAD38c",
"paperAmount": "1000000000000000000",
"creditAmount": "-21000000000",
"info": "0x00005af3107a40000001c6bf5263400000000181911c36d81cdca47ffda96bbb"
},
"hash": "0xba6f1df5d639e8a192bc4d40bc8f181404c5b1ffe149d9ca9b907008675716ab",
"createdAt": 1655996973522,
"status": "PARTIAL_FILLED",
"trades": null,
"expiration": 0
}

Get All Open Orders

GET /v1/openOrders

Parameters:

ParameterTypeMandatoryDescription
marketIdSTRINGNOMarket id

Success Response

[
{
"id": 57262765,
"account": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"marketId": "btcusdc",
"side": "BUY",
"price": "21000",
"tif": "GTC",
"averagePrice": "21010.37826087",
"type": "LIMIT",
"amount": "1",
"availableAmount": "0.31",
"filledAmount": "0.69",
"canceledAmount": "0",
"pendingAmount": "0",
"expiredAmount": "0",
"failedAmount": "0",
"json": {
"perp": "0x0eC7f726E7e64aB93dE3AA9d238684d99262c53f",
"signer": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"sender": "0x7777405dB28BcAc40F6FD2AABc62751384aAD38c",
"paperAmount": "1000000000000000000",
"creditAmount": "-21000000000",
"info": "0x00005af3107a40000001c6bf5263400000000181911c36d81cdca47ffda96bbb"
},
"hash": "0xba6f1df5d639e8a192bc4d40bc8f181404c5b1ffe149d9ca9b907008675716ab",
"createdAt": 1655996973522,
"status": "PARTIAL_FILLED",
"trades": null,
"expiration": 0
},
{
"id": 57262766,
"account": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"marketId": "btcusdc",
"side": "BUY",
"price": "21000",
"tif": "GTC",
"type": "LIMIT",
"amount": "0.1",
"availableAmount": "0.1",
"filledAmount": "0",
"canceledAmount": "0",
"pendingAmount": "0",
"expiredAmount": "0",
"failedAmount": "0",
"json": {
"perp": "0x0eC7f726E7e64aB93dE3AA9d238684d99262c53f",
"signer": "0x609c871d5D73bCC660Cb309072f4210aAC7E32fF",
"sender": "0x7777405dB28BcAc40F6FD2AABc62751384aAD38c",
"paperAmount": "100000000000000000",
"creditAmount": "-2100000000",
"info": "0x00005af3107a40000001c6bf5263400000000181911d2837a5001a5c5e2a75b6"
},
"hash": "0x34f88e38ebdca6d3df246c92673117008deb803a61c3c30f79df6efdebbd5aa5",
"createdAt": 1655997024353,
"status": "NEW",
"trades": null,
"expiration": 0
}
]

Get User Trades

GET /v1/userTrades

Parameters:

ParameterTypeMandatoryDescription
marketIdSTRINGYESMarket id
startTimeINTEGERNOTimestamp millisecond INCLUSIVE
endTimeINTEGERNOTimestamp millisecond EXCLUSIVE
limitINTEGERNODefault 100, max 500
fromIdINTEGERNOFromId cannot be sent with startTime or endTime

Success Response

[
{
"id": 15,
"commission": "-0.0149915", // Trade Fee
"isMaker": true, // Account is maker or not
"isBuyer": false, // Account side is BUY
"marketId": "btcusdc", // Market ID
"price": "29983", // Price
"amount": "0.005", // Amount in the base unit
"quoteAmount": "149.915", // Amount in quote unit
"time": 1656125389830, // Time in millisecond
"status": "SETTLED", // Trade status
"timeInForce": "GTC", // Time in force
"realizedPNL": "0", // Realized profit and loss, only exists in closing trades
"orderType": "LIMIT" // Type of order behind
},
{
"id": 23,
"commission": "-0.119924",
"isMaker": false,
"isBuyer": false,
"marketId": "btcusdc",
"price": "29981",
"amount": "0.008",
"quoteAmount": "239.848",
"time": 1656125389579,
"status": "SETTLED",
"timeInForce": "GTC",
"realizedPNL": "0",
"orderType": "LIMIT"
},
...
]

Error Response

{
"code": 1111,
"codeText": "Bad params",
"message": "fromId cannot be sent with startTime or endTime"
}

Get User Incomes

GET /v1/incomes

Parameters:

ParameterTypeMandatoryDescription
marketIdSTRINGYESMarket id
typeSTRINGNOdefault is ALL, or one of DEPOSIT WITHDRAWAL, LIQUIDATED, LIQUIDATE, TAKER_FEE MAKER_FEE BUY, SELL, FUNDING_FEE, COMMISSION, BONUS, SYSTEM, SETTLEMENT
startTimeINTEGERNOTimestamp millisecond INCLUSIVE
endTimeINTEGERNOTimestamp millisecond EXCLUSIVE
limitINTEGERNODefault 100, max 500

Success Response

[
{
"id": 3027,
"type": "FUNDING_FEE", // Income type. (More types can be found in the ENUM definitions)
"amount": "0.08781362", // Amount in usd
"time": 1656160263182, // Time in millisecond
"marketId": "btcusdc" // Market ID
},
{
"id": 3024,
"type": "FUNDING_FEE",
"amount": "0.08781362",
"time": 1656160263174,
"marketId": "btcusdc"
},
...
]

Error Response

{
"code": 1112,
"codeText": "Invalid market id",
"message": "Invalid market id"
}

Get Balances

GET /v1/balances

No Parameters

Response

{
"balances": {
"availableCreditAmounts": { // available buy/sell credit amount in quote unit
"btcusdc": {
"buy": "36080.4119586",
"sell": "26361.5246814"
}
},
"availableMargin": "1318.07623407", // available margin in quote unit
"exposure": "4935.443638", // exposure in quote unit
"frozenMargin": "1.1", // frozen margin in quote unit
"isSafe": true, // the current account is safe or not
"leverage": "3.144098", // current leverage
"marginRate": "0.318056", // current margin rate
"netValue": "1569.748416", // net value in quote unit
"pendingWithdrawPrimaryCreditAmount": "0", // pending withdraw primary credit amount in quote unit
"pendingWithdrawSecondaryCreditAmount": "0", // pending withdraw secondary credit amount in quote unit
"perpetualBalances": { // balances snapshot on the blockchain
"btcusdc": {
"creditAmount": "4801.665755",
"paperAmount": "-0.2",
"serialNumber": 3
}
},
"positionMargin": "250.57218193", // position margin in quote unit
"primaryCreditAmount": "1620.621099", // primary credit amount in quote unit
"secondaryCreditAmount": "0" // secondary credit amount in quote unit
},
"positions": [ // Refer to the `Get Open Positions` interface below
{
"marketId": "btcusdc",
"side": "SHORT",
"status": "OPEN",
"size": "0.2",
"maxSize": "0.2",
"unrealizedPnl": "-57.245939",
"realizedPnl": "0",
"entryPrice": "24010.9885",
"exitPrice": "0",
"closedAt": null,
"sumOpen": "0",
"sumClose": "0.2",
"liquidationPrice": "31191.223563",
"lastUpdatedAt": 1660145615000
}
]
}

Get Open Positions

GET /v1/positions

No Parameters

Response

[
{
"marketId": "btcusdc", // Market ID
"side": "LONG", // Position side. (More types can be found in the ENUM definitions)
"status": "OPEN", // Open or CLOSED
"size": "0.79", // Position size in the base unit
"maxSize": "0.79", // Max historical position size in the base unit
"unrealizedPnl": "130.8843", // Unrealized profit and loss in the quote unit
"realizedPnl": "0", // Realized profit and loss in the quote unit
"entryPrice": "21010.393671", // Entry price in the quote unit. (average open price of current size)
"exitPrice": "0", // Exit price in the quote unit. (average exit price of closed size)
"closedAt": null, // Time in millisecond when position is closed. (null if position is open)
"sumOpen": "0.79", // Sum of open size in the base unit
"sumClose": "0", // Sum of closed size in the base unit
"liquidationPrice": "15784.43805" // Liquidation price in the quote unit.
}
]