Spot order management
Use RestClient to manage a BTC_USDT Spot order. The examples use live services by default, so running place can spend real funds. For simulated funds, configure TestNet before running any order command.
Before submitting
- Configure authenticated access with read and trading permissions.
- Read current pair rules with
getSpotCurrencyPair(). Choose price and amount strings that meet precision, minimums and current limits. - Start the private order and fill stream with the same account and environment. Confirm the subscriptions before placing orders.
- Record a unique client order identifier in the
textfield before sending. It must begin witht-, followed by at most 28 bytes using letters, digits, underscores, hyphens or dots.
Add your own values to .env:
GATEIO_CLIENT_ORDER_ID=t-spotExample20261115001
GATEIO_LIMIT_PRICE=60000
GATEIO_ORDER_SIZE=0.0001
GATEIO_NEW_PRICE=59000Replace the example prices and amount with values that meet the current pair rules. For this buy order, choose a price below the best bid. time_in_force: 'poc' requests post-only handling, but an accepted resting order can still fill before you cancel it.
Place, inspect, amend or cancel
Save this as first-order.ts beside the credential helper. Follow its compile instructions, using first-order.ts as the entry file:
import { client, requiredEnv } from './authenticated-client.js';
async function main() {
const command = process.argv[2];
const clientOrderId = requiredEnv('GATEIO_CLIENT_ORDER_ID');
if (
!clientOrderId.startsWith('t-') ||
clientOrderId.length < 3 ||
clientOrderId.length > 30 ||
/[^A-Za-z0-9_.-]/.test(clientOrderId.slice(2))
) {
throw new Error(
'Use t- followed by 1–28 letters, digits, underscores, hyphens or dots.',
);
}
const orderId = process.env.GATEIO_ORDER_ID || clientOrderId;
const lookup = {
currency_pair: 'BTC_USDT',
account: 'spot' as const,
order_id: orderId,
};
switch (command) {
case 'place':
console.log('Submitting client order ID:', clientOrderId);
console.log(
'Order response:',
await client.submitSpotOrder({
currency_pair: 'BTC_USDT',
account: 'spot',
type: 'limit',
side: 'buy',
text: clientOrderId,
price: requiredEnv('GATEIO_LIMIT_PRICE'),
amount: requiredEnv('GATEIO_ORDER_SIZE'),
time_in_force: 'poc',
}),
);
break;
case 'status':
console.log('Order state:', await client.getSpotOrder(lookup));
break;
case 'amend':
console.log(
'Amendment response:',
await client.updateSpotOrder({
...lookup,
price: requiredEnv('GATEIO_NEW_PRICE'),
}),
);
break;
case 'cancel':
console.log(
'Cancellation response:',
await client.cancelSpotOrder(lookup),
);
break;
default:
throw new Error(
'Choose place, status, amend or cancel. Live clients use real funds.',
);
}
}
main().catch(() => {
console.error('Order command failed. Resolve its outcome before retrying.');
process.exitCode = 1;
});Run one command at a time:
node --env-file=.env dist/first-order.js place
node --env-file=.env dist/first-order.js status
node --env-file=.env dist/first-order.js amend
node --env-file=.env dist/first-order.js cancelPlacement uses GATEIO_CLIENT_ORDER_ID. After a successful placement, save the returned exchange order id as GATEIO_ORDER_ID in .env; status, amendment and cancellation use that ID when provided, otherwise they use the client identifier. Clear GATEIO_ORDER_ID before starting a different order workflow.
Gate supports custom text lookups while an order is pending and for only one hour after it finishes. Keep the exchange ID for later follow-up reads. A unique text helps correlate requests; do not assume it makes resubmission safe or prevents duplicate orders.
The example explicitly selects account: 'spot' and a limit order. Spot limit amounts are in base currency. A successful response confirms the request result, not that the order remains open. Inspect status and fills before deciding what to do next.
Recover an uncertain outcome
A timeout or disconnect does not prove the exchange rejected the command. Check private events, then query getSpotOrder() using the saved exchange or client identifier. If necessary, search finished orders with getSpotOrders({ status: 'finished', ... }) and executions with getSpotTradingHistory().
Paginate the relevant history and allow for delayed records. Do not submit a replacement while the first outcome remains unknown. An order can fill while an amendment or cancellation is being processed, so reconcile executed quantity as well as the command response.
For batch operations, inspect each item's result. Do not assume the entire batch succeeded or failed together.