Account Skill

The xbtfx-account skill provides AI agents with read-only access to account information, open positions, pending orders, and trade history.

Skill name: xbtfx-account
Type: Read-only
Required env var: XBTFX_API_KEY
Base URL: https://interface.xbtfx.com

When to Use

Check account balance, equity, free margin, or margin level
Query current leverage settings
List open positions (all or filtered by symbol)
List pending orders
Retrieve trade history for a date range

When NOT to Use

Executing trades, closing positions, or modifying SL/TP — use the Trading Skill
Looking up symbol specifications or contract sizes — use the Market Data Skill
Streaming real-time quotes or events — use the WebSocket Skill

Quick Reference

Endpoint	Method	Weight	Description
`/v1/auth/status`	GET	1	Check API key status and permissions
`/v1/account`	GET	1	Account balance, equity, and margin
`/v1/positions`	GET	1	List open positions
`/v1/orders`	GET	1	List pending orders
`/v1/history`	GET	2	Retrieve trade history

Endpoints

GET /v1/auth/status

Check the status and permissions of the current API key.

Response:

{
  "status": "active",
  "login": 12345678,
  "server": "XBTFX-Live",
  "permissions": ["read", "trade"]
}

GET /v1/account

Retrieve account balance, equity, margin, and related fields.

Response Fields:

Field	Type	Description
`login`	number	MT5 account login
`server`	string	MT5 server name
`currency`	string	Account currency (e.g., `USD`)
`balance`	number	Account balance
`equity`	number	Account equity (balance + floating P/L)
`margin`	number	Used margin
`free_margin`	number	Available margin
`margin_level`	number	Margin level as a percentage
`leverage`	number	Account leverage (e.g., `500`)
`margin_mode`	string	`hedging` or `netting`

Example Response:

{
  "login": 12345678,
  "server": "XBTFX-Live",
  "currency": "USD",
  "balance": 10000.00,
  "equity": 10250.50,
  "margin": 200.00,
  "free_margin": 10050.50,
  "margin_level": 5125.25,
  "leverage": 500,
  "margin_mode": "hedging"
}

GET /v1/positions

List all open positions, optionally filtered by symbol.

Query Parameters:

Parameter	Type	Required	Description
`symbol`	string	No	Filter positions by symbol

Response Fields:

Field	Type	Description
`ticket`	number	Position ticket number
`symbol`	string	Trading symbol
`side`	string	`buy` or `sell`
`volume`	number	Position volume in lots
`open_price`	number	Entry price
`current_price`	number	Current market price
`sl`	number	Stop-loss price (0 if not set)
`tp`	number	Take-profit price (0 if not set)
`profit`	number	Floating profit/loss
`swap`	number	Accumulated swap
`open_time`	string	Position open timestamp
`comment`	string	Trade comment

Example:

GET /v1/positions?symbol=BTCUSD

{
  "positions": [
    {
      "ticket": 12345678,
      "symbol": "BTCUSD",
      "side": "buy",
      "volume": 0.01,
      "open_price": 65000.00,
      "current_price": 65500.00,
      "sl": 60000.00,
      "tp": 70000.00,
      "profit": 5.00,
      "swap": -0.12,
      "open_time": "2025-01-15T10:30:00Z",
      "comment": ""
    }
  ]
}

GET /v1/orders

List all pending orders.

Response Fields:

Field	Type	Description
`ticket`	number	Order ticket number
`symbol`	string	Trading symbol
`type`	string	Order type
`volume`	number	Order volume in lots
`price`	number	Order trigger price
`sl`	number	Stop-loss price
`tp`	number	Take-profit price
`open_time`	string	Order placement timestamp
`comment`	string	Order comment

Order Types:

Type	Description
`buy_limit`	Buy at or below a specified price
`sell_limit`	Sell at or above a specified price
`buy_stop`	Buy when price rises to a specified level
`sell_stop`	Sell when price falls to a specified level
`buy_stop_limit`	Buy stop that places a limit order when triggered
`sell_stop_limit`	Sell stop that places a limit order when triggered

GET /v1/history

Retrieve trade history for a specified period.

Query Parameters:

Parameter	Type	Required	Description
`period`	string	No	Predefined period (default: `today`)
`from`	string	No	Start date (ISO 8601)
`to`	string	No	End date (ISO 8601)

Period Enum:

Value	Description
`today`	Current trading day
`yesterday`	Previous trading day
`week`	Current week
`month`	Current month
`custom`	Use `from` and `to` parameters

Entry Types:

Value	Description
`in`	Position opened
`out`	Position closed
`in_out`	Position opened and closed (same deal)
`out_by`	Closed by opposite position

Example:

GET /v1/history?period=week

Agent Guidelines

Agents using this skill must follow these behavioral rules:

This is a read-only skill. Never attempt to modify account state using these endpoints.
Check auth status first. Call /v1/auth/status to verify the API key is active before making other requests.
Always mask API keys in output. Never display the full API key to the user.
Present monetary values with the account currency. Use the currency field from /v1/account when displaying balances and profit/loss.
Respect rate limits. Monitor weight consumption to avoid 429 responses.
Use symbol filters when possible. Filter positions by symbol to reduce response size when the user asks about specific instruments.
Clarify margin mode to the user. The margin_mode field (hedging or netting) affects how positions and close-by operations work. Surface this information when relevant.