Skip to main content

Access Point / Host Discovery

Always resolve the Access Point for your trading account before using the Trader API, including account-scoped REST requests and WebSocket connections. Start with the Gateway host shown in the DNS widget, then use the returned Access Point for that account.

Before you start​

The DNS widget provides the Gateway host for discovery. It is not the account Access Point. Call the discovery endpoint below with the account ID before making Trader API requests for that account.

Gateway host and account Access Point​

ValueUse
Gateway host from the DNS widgetSend the discovery request to this host.
access_point returned by discoveryUse the returned Access Point for this account's REST requests and WebSocket connections.

Do not copy a hostname from an example or guess the Gateway URL from an account Access Point.

Discovery is rate limited. Resolve the Access Point once and cache it in your application instead of calling discovery before every request.

Resolve an Access Point programmatically​

The Gateway provides GET /v1/trading/access-point. It requires account_id as a query parameter: a trading account ID represented as an unsigned 64-bit integer string.

  1. 1
    Use the Gateway host from the DNS widget as the discovery base URL.
  2. 2
    Build /v1/trading/access-point?account_id=123456, replacing 123456 with your account ID.
  3. 3
    Sign the request as GET. Include the complete path and query in EXN-DATA.path, exactly as sent.
  4. 4
    Send the request and read access_point from the HTTP 200 response.
  5. 5
    Use the returned Access Point for this account's REST requests and WebSocket connections. Sign each REST request or WebSocket handshake using the exact path and query sent to the server.

For signed Trader API GET requests, the EXN-IDEMPOTENCY-KEY header is required and its value must be empty. Do not omit the header. The signed idempotency_key field in EXN-DATA must also be an empty string.

Request-shape example​

Set EXN_DISCOVERY_BASE_URL to the Gateway base URL from the DNS widget without a trailing slash. Replace the account ID and authentication placeholders before sending. This example does not generate a signature.

curl "${EXN_DISCOVERY_BASE_URL}/v1/trading/access-point?account_id=123456" \
  -H "EXN-API-KEY: <your-api-key>" \
  -H "EXN-IDEMPOTENCY-KEY;" \
  -H "EXN-TIMESTAMP: <fresh-unix-milliseconds>" \
  -H "EXN-SIGN-VERSION: 1" \
  -H "EXN-DATA: <base64url-encoded-signed-data>" \
  -H "EXN-SIGN: <base64url-encoded-signature>"

The semicolon in curl's EXN-IDEMPOTENCY-KEY; option sends the required header with an empty value. For this example, the signed path is /v1/trading/access-point?account_id=123456, not a full URL.

Illustrative HTTP 200 response; the URL is a placeholder:

{
  "access_point": "https://access-point.example",
  "account_id": "123456"
}

access_point is a URL. The echoed account_id is a string, not a JSON number.

Continue with the selected host​

  1. 1
    Send your first REST request to read account details. Replace the example host and account ID with your selected values.
  2. 2
    Sign the exact request path and query as described in Request signing. The signed path is not a full URL.
  3. 3
    For streams, follow Subscribe to WebSocket Events. Sign the handshake as GET using the exact connection path and query sent to the server.

If discovery fails​

HTTP statusWhat to check
400Check the required account_id query parameter and request format.
401Check the API key, signed headers and signature.
403Check access to the requested account.
429Retry after the time indicated by Retry-After or retry_after.
500Read the response's description for more information.
503The service is temporarily unavailable; retry later.

If the Gateway host is unavailable, obtain it from Key Management before sending the discovery request. Do not switch to a hostname copied from an example.