Place an order
curl --request POST \
--url https://api.gains.trade/v1/{chain}/orders \
--header 'Content-Type: application/json' \
--header 'X-Gains-Signature: <api-key>' \
--data '
{
"market": "BTC/USD",
"size": "0.5",
"leverage": "0.5",
"price": "0.5",
"collateral": "<string>",
"sl": "0.5",
"tp": "0.5",
"reduceOnly": true,
"slippage": "0.5",
"clientId": "<string>"
}
'import requests
url = "https://api.gains.trade/v1/{chain}/orders"
payload = {
"market": "BTC/USD",
"size": "0.5",
"leverage": "0.5",
"price": "0.5",
"collateral": "<string>",
"sl": "0.5",
"tp": "0.5",
"reduceOnly": True,
"slippage": "0.5",
"clientId": "<string>"
}
headers = {
"X-Gains-Signature": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Gains-Signature': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
market: 'BTC/USD',
size: '0.5',
leverage: '0.5',
price: '0.5',
collateral: '<string>',
sl: '0.5',
tp: '0.5',
reduceOnly: true,
slippage: '0.5',
clientId: '<string>'
})
};
fetch('https://api.gains.trade/v1/{chain}/orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gains.trade/v1/{chain}/orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'market' => 'BTC/USD',
'size' => '0.5',
'leverage' => '0.5',
'price' => '0.5',
'collateral' => '<string>',
'sl' => '0.5',
'tp' => '0.5',
'reduceOnly' => true,
'slippage' => '0.5',
'clientId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Gains-Signature: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gains.trade/v1/{chain}/orders"
payload := strings.NewReader("{\n \"market\": \"BTC/USD\",\n \"size\": \"0.5\",\n \"leverage\": \"0.5\",\n \"price\": \"0.5\",\n \"collateral\": \"<string>\",\n \"sl\": \"0.5\",\n \"tp\": \"0.5\",\n \"reduceOnly\": true,\n \"slippage\": \"0.5\",\n \"clientId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Gains-Signature", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gains.trade/v1/{chain}/orders")
.header("X-Gains-Signature", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"market\": \"BTC/USD\",\n \"size\": \"0.5\",\n \"leverage\": \"0.5\",\n \"price\": \"0.5\",\n \"collateral\": \"<string>\",\n \"sl\": \"0.5\",\n \"tp\": \"0.5\",\n \"reduceOnly\": true,\n \"slippage\": \"0.5\",\n \"clientId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gains.trade/v1/{chain}/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Gains-Signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"market\": \"BTC/USD\",\n \"size\": \"0.5\",\n \"leverage\": \"0.5\",\n \"price\": \"0.5\",\n \"collateral\": \"<string>\",\n \"sl\": \"0.5\",\n \"tp\": \"0.5\",\n \"reduceOnly\": true,\n \"slippage\": \"0.5\",\n \"clientId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"order": {
"id": "5316911983139663",
"trader": "0x73b3A111C5BCCf9086c97B96e0AbAad69Dc4f523",
"market": "BTC/USD",
"side": "long",
"type": "market",
"size": "0.5",
"price": "0.5",
"leverage": "0.5",
"collateral": "<string>",
"sl": "0.5",
"tp": "0.5",
"reduceOnly": true,
"slippage": "0.5",
"clientId": "<string>",
"status": "prepared",
"txHash": "0xabc123",
"expiresAt": 123,
"fill": {
"price": "0.5",
"size": "0.5",
"collateral": "0.5",
"feeCollateral": "0.5",
"txHash": "0xabc123",
"timestamp": 123,
"positionId": "5316911983139663"
},
"reason": "NONE",
"createdAt": 123,
"updatedAt": 123
},
"transaction": {
"to": "0x73b3A111C5BCCf9086c97B96e0AbAad69Dc4f523",
"data": "0xabc123",
"value": "0",
"chainId": 123,
"gas": "<string>",
"expiresAt": 123
}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}Orders
Place an order
Validates the order, checks the agent scope, simulates it from the agent and returns the transaction the agent signs and broadcasts (transaction) together with the order in prepared state and its final id. After broadcasting, POST /orders/{id}/submit with the hash; the order becomes pending (market) or open (limit, stop). The API also watches the chain, so a prepared order whose transaction lands moves on without the submit call.
POST
/
v1
/
{chain}
/
orders
Place an order
curl --request POST \
--url https://api.gains.trade/v1/{chain}/orders \
--header 'Content-Type: application/json' \
--header 'X-Gains-Signature: <api-key>' \
--data '
{
"market": "BTC/USD",
"size": "0.5",
"leverage": "0.5",
"price": "0.5",
"collateral": "<string>",
"sl": "0.5",
"tp": "0.5",
"reduceOnly": true,
"slippage": "0.5",
"clientId": "<string>"
}
'import requests
url = "https://api.gains.trade/v1/{chain}/orders"
payload = {
"market": "BTC/USD",
"size": "0.5",
"leverage": "0.5",
"price": "0.5",
"collateral": "<string>",
"sl": "0.5",
"tp": "0.5",
"reduceOnly": True,
"slippage": "0.5",
"clientId": "<string>"
}
headers = {
"X-Gains-Signature": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Gains-Signature': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
market: 'BTC/USD',
size: '0.5',
leverage: '0.5',
price: '0.5',
collateral: '<string>',
sl: '0.5',
tp: '0.5',
reduceOnly: true,
slippage: '0.5',
clientId: '<string>'
})
};
fetch('https://api.gains.trade/v1/{chain}/orders', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.gains.trade/v1/{chain}/orders",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'market' => 'BTC/USD',
'size' => '0.5',
'leverage' => '0.5',
'price' => '0.5',
'collateral' => '<string>',
'sl' => '0.5',
'tp' => '0.5',
'reduceOnly' => true,
'slippage' => '0.5',
'clientId' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Gains-Signature: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.gains.trade/v1/{chain}/orders"
payload := strings.NewReader("{\n \"market\": \"BTC/USD\",\n \"size\": \"0.5\",\n \"leverage\": \"0.5\",\n \"price\": \"0.5\",\n \"collateral\": \"<string>\",\n \"sl\": \"0.5\",\n \"tp\": \"0.5\",\n \"reduceOnly\": true,\n \"slippage\": \"0.5\",\n \"clientId\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Gains-Signature", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.gains.trade/v1/{chain}/orders")
.header("X-Gains-Signature", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"market\": \"BTC/USD\",\n \"size\": \"0.5\",\n \"leverage\": \"0.5\",\n \"price\": \"0.5\",\n \"collateral\": \"<string>\",\n \"sl\": \"0.5\",\n \"tp\": \"0.5\",\n \"reduceOnly\": true,\n \"slippage\": \"0.5\",\n \"clientId\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.gains.trade/v1/{chain}/orders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Gains-Signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"market\": \"BTC/USD\",\n \"size\": \"0.5\",\n \"leverage\": \"0.5\",\n \"price\": \"0.5\",\n \"collateral\": \"<string>\",\n \"sl\": \"0.5\",\n \"tp\": \"0.5\",\n \"reduceOnly\": true,\n \"slippage\": \"0.5\",\n \"clientId\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"order": {
"id": "5316911983139663",
"trader": "0x73b3A111C5BCCf9086c97B96e0AbAad69Dc4f523",
"market": "BTC/USD",
"side": "long",
"type": "market",
"size": "0.5",
"price": "0.5",
"leverage": "0.5",
"collateral": "<string>",
"sl": "0.5",
"tp": "0.5",
"reduceOnly": true,
"slippage": "0.5",
"clientId": "<string>",
"status": "prepared",
"txHash": "0xabc123",
"expiresAt": 123,
"fill": {
"price": "0.5",
"size": "0.5",
"collateral": "0.5",
"feeCollateral": "0.5",
"txHash": "0xabc123",
"timestamp": 123,
"positionId": "5316911983139663"
},
"reason": "NONE",
"createdAt": 123,
"updatedAt": 123
},
"transaction": {
"to": "0x73b3A111C5BCCf9086c97B96e0AbAad69Dc4f523",
"data": "0xabc123",
"value": "0",
"chainId": 123,
"gas": "<string>",
"expiresAt": 123
}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}{
"code": "VALIDATION_ERROR",
"message": "<string>",
"details": {}
}Authorizations
EIP-712 signature by an authorised agent over {method, path, body, timestamp, nonce}, sent with X-Gains-Agent, X-Gains-Timestamp and X-Gains-Nonce.
Path Parameters
Available options:
arbitrum, base, polygon, megaeth, arbitrum-sepolia Example:
"arbitrum"
Body
application/json
The order
Gains market symbol, <base>/<quote>.
Pattern:
^[A-Z0-9.]{1,15}\/[A-Z0-9]{1,10}$Example:
"BTC/USD"
Available options:
long, short Available options:
market, limit, stop Position size in base asset units.
Pattern:
^-?(?:0|[1-9]\d*)(?:\.\d+)?$Example:
"0.5"
Decimal number encoded as a string to preserve precision.
Pattern:
^-?(?:0|[1-9]\d*)(?:\.\d+)?$Example:
"0.5"
Trigger price for limit/stop orders; expected price for market orders (defaults to the mark price).
Pattern:
^-?(?:0|[1-9]\d*)(?:\.\d+)?$Example:
"0.5"
Collateral symbol. Defaults to USDC where the chain lists it, otherwise to the chain's single active collateral.
Decimal number encoded as a string to preserve precision.
Pattern:
^-?(?:0|[1-9]\d*)(?:\.\d+)?$Example:
"0.5"
Decimal number encoded as a string to preserve precision.
Pattern:
^-?(?:0|[1-9]\d*)(?:\.\d+)?$Example:
"0.5"
Defaults to false.
Maximum slippage in percent. Defaults to 1.
Pattern:
^-?(?:0|[1-9]\d*)(?:\.\d+)?$Example:
"0.5"
Required string length:
1 - 64