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
price	number	No	Advisory price. Bridge uses MT5 server price for market orders.
comment	string	No	Trade comment (max 27 characters)

Supports idempotency via the Idempotency-Key header.

Example:

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

Response:

{
  "status": "placed",
  "retcode": 10008,
  "volume": 0.10,
  "comment": ""
}

Note

The response status is placed when the trade request is accepted. Conditional fields deal, order, and price are included when available (e.g., when the order is immediately filled).

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)
comment	string	No	Close comment (max 27 characters)
price	number	No	Advisory price. Bridge uses MT5 server price.

Supports idempotency via the Idempotency-Key header.

Example:

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

Response:

{
  "status": "placed",
  "retcode": 10008
}

Note

Conditional fields deal and price are included when available.

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)

Supports idempotency via the Idempotency-Key header.

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
position	number	Yes	Position ticket to close
position_by	number	Yes	Opposite position ticket
comment	string	No	Close comment (max 27 characters)

Supports idempotency via the Idempotency-Key header.

Example:

POST /v1/close-by
{
  "position": 12345678,
  "position_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
comment	string	No	Trade comment (max 27 characters)

Supports idempotency via the Idempotency-Key header.

Example:

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

POST /v1/close-all

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

Parameters:

Parameter	Type	Required	Description
comment	string	No	Close comment (max 27 characters)

Supports idempotency via the Idempotency-Key header.

Example:

POST /v1/close-all
{}

Response:

{
  "closed": 3,
  "failed": 0,
  "total_profit": 125.50,
  "details": []
}

Caution

This endpoint closes every open position on the account. The response may return HTTP 207 if some positions close successfully while others fail. Inspect details[] for per-position results when failed > 0.

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
comment	string	No	Close comment (max 27 characters)

Supports idempotency via the Idempotency-Key header.

Example:

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

Response:

{
  "closed": 2,
  "failed": 0,
  "total_profit": 75.00,
  "details": []
}

Enums

Side

Value	Description
buy	Long position
sell	Short position

Status

Value	Description
placed	Trade request accepted by the server (may fill immediately)
filled	Trade executed and fully filled
ok	Modification or close succeeded
rejected	Operation was rejected by the server

Idempotency

All POST endpoints support idempotency via the Idempotency-Key HTTP header. 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).

Example header:

Idempotency-Key: trade-abc-123

See Idempotency for full details.

Error Codes

Code	Meaning
400	Invalid parameters
400 market_closed	Market is closed. Response includes next_open.
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. Send a unique Idempotency-Key header (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.