Private HTTP API
Authentication
Please refer to the Private endpoint authentication section.
Endpoints
Register Account
Register Account
POST /v1/account
Parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| account | STRING | YES | Ethereum address |
Success Response
{
"address": "0x0000000000000000000000000000000000000003",
"createdAt": 1655774600530,
}
Error Response
{
"code": 2018,
"codeText": "Duplicated account",
"message": "Duplicated"
}
Get Account
GET /v1/account
Parameters:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| account | STRING | YES | Ethereum 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,
The first way is to directly interact with the api to construct the order without understanding the order data structure in the contract.
- Pass in the parameters to call the Build Unsigned Order API, and get the orderHash and info.
- 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.
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.HexToHash(contractAddress).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
)
paperAmount = decimal.RequireFromString(amount).Shift(18)
creditAmount := decimal.RequireFromString(price).Mul(paperAmount.Shift(-18)).Shift(creditDecimals)
if side == "BUY" {
creditAmount = creditAmount.Ceil().Neg()
} else {
creditAmount = creditAmount.Floor()
paperAmount = paperAmount.Neg()
}
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:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| marketId | STRING | YES | Market id |
| side | STRING | YES | BUY or SELL. |
| orderType | STRING | YES | MARKET, LIMIT |
| amount | STRING | YES | Amount of the order, in base asset (i.e. an BTC-USDC position of size 1 represents 1 ETH). |
| price | STRING | YES | Worst accepted price of the base asset. |
| timeInForce | STRING | YES | One of GTC (Good til cancel), FOK(Fill or kill), IOC (Immediate or cancel) or GTT (Good Til Time). This will default to GTC. |
| expiration | LONG | NO | Only 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:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| marketId | STRING | YES | Market id |
| side | STRING | YES | BUY or SELL. |
| orderType | STRING | YES | MARKET, LIMIT |
| amount | STRING | YES | Amount of the order, in base asset (i.e. an BTC-USDC position of size 1 represents 1 ETH). |
| price | STRING | YES | Worst accepted price of the base asset. |
| timeInForce | STRING | YES | One of GTC (Good til cancel), FOK(Fill or kill), IOC (Immediate or cancel) or GTT (Good Til Time). This will default to GTC. |
| orderSignature | STRING | YES | Signature for the order, Sign the orderHash returned in the build order. |
| info | STRING | YES | Info 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. |
| expiration | LONG | NO | Only GTT (Good Til Time) supports expiration time, and the expiration time must be greater than 1 minute and less than 7 days. |
| gasFeeQuotation | STRING | YES | 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:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| marketId | STRING | YES | Market id |
| orderId | INTEGER | YES | Order 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:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| marketId | STRING | NO | Market 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:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| marketId | STRING | YES | Market id |
| startTime | INTEGER | NO | Timestamp millisecond |
| endTime | INTEGER | NO | Timestamp millisecond |
| limit | INTEGER | NO | Default 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:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| marketId | STRING | YES | Market id. |
| orderId | INTEGER | YES | Order 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:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| marketId | STRING | NO | Market id |
| orderId | INTEGER | NO | Order 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:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| marketId | STRING | NO | Market 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:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| marketId | STRING | YES | Market id |
| startTime | INTEGER | NO | Timestamp millisecond INCLUSIVE |
| endTime | INTEGER | NO | Timestamp millisecond EXCLUSIVE |
| limit | INTEGER | NO | Default 100, max 500 |
| fromId | INTEGER | NO | FromId 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:
| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| marketId | STRING | YES | Market id |
| type | STRING | NO | default is ALL, or one of DEPOSIT WITHDRAWAL, LIQUIDATED, LIQUIDATE, TAKER_FEE MAKER_FEE BUY, SELL, FUNDING_FEE, COMMISSION, BONUS, SYSTEM, SETTLEMENT |
| startTime | INTEGER | NO | Timestamp millisecond INCLUSIVE |
| endTime | INTEGER | NO | Timestamp millisecond EXCLUSIVE |
| limit | INTEGER | NO | Default 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.
}
]