Getting started on the exchange

The STX exchange exposes a GraphQL API over HTTP and a real-time WebSocket API via Phoenix Channels. This guide walks you through setting up your environment, authenticating, and placing your first trade.

All API calls go to:

POST /api/graphql          # HTTP GraphQL
wss://<host>/socket/websocket  # WebSocket

---

1. Install Dependencies

Pick your language and install the required packages.

=== “Python”

```bash
pip install requests
```

Python's built-in `http.client` works too, but `requests` is simpler for JSON APIs.

=== “JavaScript”

```bash
# No extra package needed — native fetch is available in Node 18+ and all browsers.
# Optional: install graphql-request for a typed client
npm install graphql-request
```

=== “Elixir”

mix.exs

Add `req` to your `mix.exs` dependencies:

```elixir
defp deps do
  [
    {:req, "~> 0.5"}
  ]
end
```

Then fetch:

```bash
mix deps.get
```

---

2. Configure Your Client

Set your API base URL and token. The token is obtained from the login mutation and must be sent as a bearer token on every subsequent request.

=== “Python”

```python
import requests

BASE_URL = "https://api.example.com"
TOKEN = None  # set after login

def gql(query, variables=None, token=None):
    headers = {"Content-Type": "application/json"}
    if token:
        headers["Authorization"] = f"Bearer {token}"
    resp = requests.post(
        f"{BASE_URL}/api/graphql",
        headers=headers,
        json={"query": query, "variables": variables or {}}
    )
    resp.raise_for_status()
    return resp.json()
```

=== “JavaScript”

```javascript
const BASE_URL = "https://api.example.com";
let token = null; // set after login

async function gql(query, variables = {}) {
  const headers = { "Content-Type": "application/json" };
  if (token) headers["Authorization"] = `Bearer ${token}`;

  const response = await fetch(`${BASE_URL}/api/graphql`, {
    method: "POST",
    headers,
    body: JSON.stringify({ query, variables })
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}
```

=== “Elixir”

```elixir
defmodule StxClient do
  @base_url "https://api.example.com"

  def gql(query, variables \\ %{}, token \\ nil) do
    headers =
      [{"Content-Type", "application/json"}]
      |> then(fn h ->
        if token, do: [{"Authorization", "Bearer #{token}"} | h], else: h
      end)

    Req.post!(
      "#{@base_url}/api/graphql",
      headers: headers,
      json: %{query: query, variables: variables}
    ).body
  end
end
```

---

3. Log In

Call the login mutation with your email and password. On success you receive a short-lived token and a long-lived refreshToken.

!!! note “2FA accounts” If your account has two-factor authentication enabled, login returns status: "2fa_required" and a sessionId. Email a one-time code to the user, then call confirm2Fa with the code, email, and sessionId to complete login.

=== “Python”

```python
LOGIN = """
  mutation Login($credentials: LoginCredentials!) {
    login(credentials: $credentials) {
      token
      refreshToken
      status
    }
  }
"""

result = gql(LOGIN, {"credentials": {"email": "you@example.com", "password": "secret"}})
data = result["data"]["login"]
token = data["token"]
```

=== “JavaScript”

```javascript
const LOGIN = `
  mutation Login($credentials: LoginCredentials!) {
    login(credentials: $credentials) {
      token
      refreshToken
      status
    }
  }
`;

const { data } = await gql(LOGIN, {
  credentials: { email: "you@example.com", password: "secret" }
});
token = data.login.token;
```

=== “Elixir”

```elixir
login_query = """
  mutation Login($credentials: LoginCredentials!) {
    login(credentials: $credentials) {
      token
      refreshToken
      status
    }
  }
"""

%{"data" => %{"login" => %{"token" => token}}} =
  StxClient.gql(login_query, %{
    credentials: %{email: "you@example.com", password: "secret"}
  })
```

---

4. Make an Authenticated Request

With a token in hand, fetch your account profile:

=== “Python”

```python
PROFILE = """
  query UserProfile {
    userProfile {
      email
      username
      createdAt
    }
  }
"""

profile = gql(PROFILE, token=token)["data"]["userProfile"]
print(profile)
```

=== “JavaScript”

```javascript
const PROFILE = `
  query UserProfile {
    userProfile {
      email
      username
      createdAt
    }
  }
`;

const { data } = await gql(PROFILE);
console.log(data.userProfile);
```

=== “Elixir”

```elixir
profile_query = """
  query UserProfile {
    userProfile {
      email
      username
      createdAt
    }
  }
"""

%{"data" => %{"userProfile" => profile}} =
  StxClient.gql(profile_query, %{}, token)

IO.inspect(profile)
```

---

Next Steps

• Create an Account — registration and email verification flow
• Verify & Activate — identity verification and deposit requirements
• Place Your First Trade — browse markets, read odds, and submit an order
• GraphQL Reference — complete mutation and query documentation
• WebSocket Channels — real-time order book and fill notifications