Trading Skill

The xbtfx-trading skill provides AI agents with the ability to execute trades and manage positions on the XBTFX platform.

• Skill name: xbtfx-trading
• Required env var: XBTFX_API_KEY
• Base URL: https://interface.xbtfx.com

When to Use

• Execute market trades (buy/sell)
• Close open positions
• Modify stop-loss and take-profit levels
• Reverse an existing position
• Close a position by its opposite (hedging accounts)
• Close all positions or all positions for a symbol

When NOT to Use

• Market commentary or analysis — this skill only executes actions
• Read-only account checks (balance, equity, margin) — use the Account Skill
• Symbol specifications, contract sizes, volume constraints — use the Market Data Skill

Quick Reference

Endpoint	Method	Weight	Description
/v1/trade	POST	1	Open a market position
/v1/close	POST	1	Close a specific position
/v1/modify	POST	1	Modify SL/TP on a position
/v1/close-by	POST	1	Close position by opposite (hedging)
/v1/reverse	POST	2	Reverse a position atomically
/v1/close-all	POST	10	Close all open positions
/v1/close-symbol	POST	10	Close all positions for a symbol

Endpoints

POST /v1/trade

Open a new market position.

Parameters:

Parameter	Type	Required	Description
symbol	string	Yes	Trading symbol (e.g., BTCUSD)
side	string	Yes	buy or sell
volume	number	Yes	Trade volume in lots
sl	number	No	Stop-loss price
tp	number	No	Take-profit price
comment	string	No	Trade comment (max 27 characters)
idempotency_key	string	No	Unique key to prevent duplicates

Example:

POST /v1/trade
{
  "symbol": "BTCUSD",
  "side": "buy",
  "volume": 0.01,
  "sl": 60000,
  "tp": 70000,
  "comment": "ai-trade",
  "idempotency_key": "trade-abc-123"
}

Response:

{
  "status": "filled",
  "ticket": 12345678,
  "symbol": "BTCUSD",
  "side": "buy",
  "volume": 0.01,
  "price": 65000.00
}

POST /v1/close

Close a specific open position by ticket number.

Parameters:

Parameter	Type	Required	Description
ticket	number	Yes	Position ticket to close
volume	number	No	Partial close volume (omit for full close)
idempotency_key	string	No	Unique key to prevent duplicates

Example:

POST /v1/close
{
  "ticket": 12345678
}

POST /v1/modify

Modify stop-loss and/or take-profit on an open position or pending order.

Parameters:

Parameter	Type	Required	Description
ticket	number	Yes	Position or order ticket
sl	number	No	New stop-loss price (0 to remove)
tp	number	No	New take-profit price (0 to remove)
idempotency_key	string	No	Unique key to prevent duplicates

Example:

POST /v1/modify
{
  "ticket": 12345678,
  "sl": 61000,
  "tp": 72000
}

POST /v1/close-by

Close a position using an opposite position on the same symbol. Only available on hedging accounts.

Parameters:

Parameter	Type	Required	Description
ticket	number	Yes	Position ticket to close
ticket_by	number	Yes	Opposite position ticket
idempotency_key	string	No	Unique key to prevent duplicates

Example:

POST /v1/close-by
{
  "ticket": 12345678,
  "ticket_by": 12345679
}

POST /v1/reverse

Reverse a position atomically. This closes the current position and opens a new one in the opposite direction. Consumes 2 weight units.

Parameters:

Parameter	Type	Required	Description
ticket	number	Yes	Position ticket to reverse
volume	number	No	Volume for the new position (defaults to original)
sl	number	No	Stop-loss for the new position
tp	number	No	Take-profit for the new position
idempotency_key	string	No	Unique key to prevent duplicates

Example:

POST /v1/reverse
{
  "ticket": 12345678,
  "sl": 64000,
  "tp": 58000
}

POST /v1/close-all

Close all open positions on the account. Consumes 10 weight units.

Parameters:

Parameter	Type	Required	Description
idempotency_key	string	No	Unique key to prevent duplicates

Example:

POST /v1/close-all
{}

Caution

This endpoint closes every open position on the account. The response may return HTTP 207 if some positions close successfully while others fail.

POST /v1/close-symbol

Close all open positions for a specific symbol. Consumes 10 weight units.

Parameters:

Parameter	Type	Required	Description
symbol	string	Yes	Symbol to close all positions for
idempotency_key	string	No	Unique key to prevent duplicates

Example:

POST /v1/close-symbol
{
  "symbol": "BTCUSD"
}

Enums

Side

Value	Description
buy	Long position
sell	Short position

Status

Value	Description
filled	Trade executed successfully
placed	Pending order placed
ok	Modification or close succeeded
rejected	Operation was rejected by the server

Idempotency

All POST endpoints accept an idempotency_key parameter. If a request with the same key has already been processed, the server returns the original response instead of executing the operation again.

Use idempotency keys for all trade operations to prevent duplicate executions from retries or network issues. Keys should be unique per intended operation (e.g., UUID v4).

See Idempotency for full details.

Error Codes

Code	Meaning
400	Invalid parameters
401	Authentication failed
403	Insufficient permissions
404	Position or order not found
207	Partial success (bulk operations)
429	Rate limit exceeded
500	Internal server error

See Error Codes for the complete reference.

Agent Guidelines

Agents using this skill must follow these behavioral rules:

1. Always confirm before executing trades. Never open, close, or modify positions without explicit user confirmation.
2. Check symbol specifications first. Use the Market Data Skill to verify volume constraints, contract size, and trading hours before placing trades.
3. Check the account margin mode. Determine whether the account uses hedging or netting before using close-by or reverse operations.
4. Use idempotency keys on every trade request. Generate a unique key (UUID v4) for each intended operation to prevent duplicate executions.
5. Handle HTTP 207 responses. Bulk operations (close-all, close-symbol) may partially succeed. Inspect each result in the response array.
6. Never mask or hide ticket numbers. Always display position tickets to the user so they can verify operations.
7. Always mask API keys in output. Never display the full API key to the user.
8. Respect rate limits. Trading endpoints consume weight as listed in the quick reference table. Monitor usage to avoid 429 responses.
9. Volume is always in lots. Do not confuse lots with units or contract size. Check the symbol specification for lot constraints.
10. Comments are optional and limited to 27 characters. Use them for tagging trades, not for long descriptions.
11. Maximum 200 open positions per account. Check current position count before opening new trades.