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,
  "permissions": ["read", "trade"],
  "margin_mode": "hedging",
  "tier": "standard"
}

GET /v1/account

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

Response Fields:

Field	Type	Description
`login`	number	MT5 account login
`balance`	number	Account balance
`equity`	number	Account equity (balance + floating P/L)
`margin`	number	Used margin
`margin_free`	number	Available margin
`profit`	number	Current floating profit/loss
`leverage`	number	Account leverage (e.g., `500`)
`margin_mode`	string	`hedging` or `netting`

Example Response:

{
  "login": 12345678,
  "balance": 10000.00,
  "equity": 10250.50,
  "margin": 200.00,
  "margin_free": 10050.50,
  "profit": 250.50,
  "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
`price_open`	number	Entry price
`price_current`	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

The response includes a count field with the total number of positions.

Example:

GET /v1/positions?symbol=BTCUSD

{
  "positions": [
    {
      "ticket": 12345678,
      "symbol": "BTCUSD",
      "side": "buy",
      "volume": 0.01,
      "price_open": 65000.00,
      "price_current": 65500.00,
      "sl": 60000.00,
      "tp": 70000.00,
      "profit": 5.00,
      "swap": -0.12
    }
  ],
  "count": 1
}

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

The response includes a count field with the total number of orders.

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 (`YYYY-MM-DD`), alternative to `period`
`to`	string	No	End date (`YYYY-MM-DD`), alternative to `period`

Use either period for a predefined range, or from/to for a custom date range.

Period Enum:

Value	Description
`today`	Current trading day
`last_3_days`	Last 3 days
`last_week`	Last 7 days
`last_month`	Last 30 days
`last_3_months`	Last 90 days
`last_6_months`	Last 180 days
`all`	All available history

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=last_week

Response:

{
  "deals": [
    {
      "ticket": 99001122,
      "symbol": "EURUSD",
      "side": "buy",
      "entry": "in",
      "volume": 0.10,
      "price": 1.08550,
      "profit": 0.00,
      "time": "2025-01-15T10:30:00Z",
      "order": 88001122,
      "position": 12345678
    }
  ],
  "count": 1
}

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 clearly. Display balances and profit/loss with appropriate formatting.
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.