Market Data Skill

The xbtfx-market-data skill provides AI agents with read-only access to symbol specifications, volume constraints, contract sizes, and live bid/ask prices.

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

When to Use

• Look up available trading symbols
• Check volume constraints (min, max, step) before placing trades
• Retrieve contract sizes and point values
• Get the current bid/ask spread for a symbol
• Verify trading hours and session times

When NOT to Use

• Executing trades or managing positions — use the Trading Skill
• Checking account balance, equity, or margin — use the Account Skill
• Streaming real-time quotes continuously — use the WebSocket Skill

Quick Reference

Endpoint	Method	Weight	Description
/v1/symbols	GET	2	List all available trading symbols
/v1/symbols/:symbol	GET	1	Get specification for a single symbol

Endpoints

GET /v1/symbols

List all available trading symbols and their specifications.

Note

This endpoint returns the full symbol list and consumes 2 weight units. If you only need one symbol, use the single-symbol endpoint instead.

GET /v1/symbols/:symbol

Get the specification for a single trading symbol.

Path Parameters:

Parameter	Type	Required	Description
symbol	string	Yes	Symbol name (e.g., BTCUSD)

Response Fields:

Field	Type	Description
symbol	string	Symbol name
description	string	Human-readable description
currency_base	string	Base currency
currency_profit	string	Profit currency
currency_margin	string	Margin currency
contract_size	number	Contract size per lot
volume_min	number	Minimum trade volume in lots
volume_max	number	Maximum trade volume in lots
volume_step	number	Volume increment step
digits	number	Price decimal places
point	number	Minimum price change
spread	number	Current spread in points
bid	number	Current bid price
ask	number	Current ask price
trade_mode	string	Trading mode (e.g., full)
swap_long	number	Swap rate for long positions
swap_short	number	Swap rate for short positions

Example:

GET /v1/symbols/BTCUSD

{
  "symbol": "BTCUSD",
  "description": "Bitcoin vs US Dollar",
  "currency_base": "BTC",
  "currency_profit": "USD",
  "currency_margin": "USD",
  "contract_size": 1,
  "volume_min": 0.01,
  "volume_max": 10.0,
  "volume_step": 0.01,
  "digits": 2,
  "point": 0.01,
  "spread": 50,
  "bid": 65000.00,
  "ask": 65000.50,
  "trade_mode": "full",
  "swap_long": -15.0,
  "swap_short": -5.0
}

Volume Validation

Before placing a trade, agents must validate the requested volume against the symbol specification. A valid volume must satisfy:

volume_min <= volume <= volume_max
(volume - volume_min) % volume_step == 0

Examples for BTCUSD (min: 0.01, max: 10.0, step: 0.01):

Volume	Valid	Reason
0.01	Yes	Equals volume_min
0.05	Yes	Within range, divisible by step
1.00	Yes	Within range, divisible by step
0.005	No	Below volume_min and not divisible by step
10.01	No	Exceeds volume_max

Tip

Always fetch the symbol specification before placing a trade. Volume constraints vary by instrument and can change.

Agent Guidelines

Agents using this skill must follow these behavioral rules:

1. This is a read-only skill. These endpoints do not modify any account state.
2. Always check symbol specs before trading. Call /v1/symbols/:symbol to verify volume constraints and trading availability before using the Trading Skill.
3. Validate volume before trade requests. Use the volume validation formula to ensure the requested volume is valid for the instrument.
4. Prefer the single-symbol endpoint. Use /v1/symbols/:symbol (weight 1) instead of /v1/symbols (weight 2) when you only need one symbol.
5. Always mask API keys in output. Never display the full API key to the user.
6. Respect rate limits. The full symbol list endpoint consumes 2 weight units. Avoid calling it repeatedly.
7. Spread is in points, not price units. To convert spread to price: spread * point. For example, a spread of 50 with point 0.01 equals a price spread of 0.50.