Idempotency

The XBTFX Trading API supports idempotency keys to safely retry requests without risking duplicate operations. This is critical for trade execution, where a network timeout could leave you unsure whether a trade was placed.

How It Works

Include an Idempotency-Key header with a unique identifier on your request. If the API receives a second request with the same key within the TTL window, it returns the original response instead of executing the operation again.

• TTL: 120 seconds (2 minutes)
• Scope: Per API key. Two different API keys can use the same idempotency key value without conflict.

Supported Endpoints

Idempotency keys are supported on mutating endpoints:

• POST /v1/trade
• POST /v1/close
• POST /v1/modify
• POST /v1/close-by
• POST /v1/reverse

Example

curl -X POST https://interface.xbtfx.com/v1/trade \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "symbol": "EURUSD",
    "side": "buy",
    "volume": 0.1
  }'

If this request is sent again with the same Idempotency-Key within 120 seconds, the API returns the cached response from the first execution rather than opening a second trade.

Best Practices

• Use UUIDs. Generate a UUID v4 for each logical operation to guarantee uniqueness.
• Generate before sending. Create the key before the request, not after. This ensures retries use the same key.
• One key per operation. Do not reuse an idempotency key for a different operation. Each distinct trade, close, or modify should have its own key.
• Retry promptly. Keys expire after 120 seconds. If you need to retry after that window, the key will no longer be recognized and the operation will execute again.