> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sportsxapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Regions, environments, profile files, and schema pinning.

## Region and environment

Every client takes two top-level kwargs that pick the backend:

| Kwarg    | Values                                                 | Default                                   |
| -------- | ------------------------------------------------------ | ----------------------------------------- |
| `region` | `"ontario"`, `"us"` (pending)                          | — (required)                              |
| `env`    | `"production"`, `"staging"`, `"dev"`, `"qa"`, `"demo"` | `"staging"` if env var `STX_ENV` is unset |

```python theme={null}
from stx import STX

STX(region="ontario", env="staging")        # api-staging.on.sportsxapp.com
STX(region="ontario", env="production")     # api.on.sportsxapp.com
STX(region="ontario", env="dev")            # api-dev.on.sportsxapp.com
```

<Note>
  US region hosts are not live yet. Pass `region="ontario"` for all current environments.
</Note>

### Precedence

`env` resolves in this order (highest wins):

1. Keyword argument — `STX(env="production")`
2. Environment variable — `STX_ENV=production`
3. Profile file — `env = production` in `~/.stx/credentials`
4. Default — `"staging"`

Unknown env names raise `STXException` at construction time.

### Custom hosts

For local development against a custom host — a branch-deployed preview, or `localhost`:

```python theme={null}
STX(host="http://localhost:4000", email="...", password="...")
```

Passing `host=` **bypasses the region/env table entirely** — the SDK won't try to look up a hostname. Useful for testing, not recommended in production code.

## Environment variables

The SDK reads these at client-construction time:

| Variable            | Purpose                                                             |
| ------------------- | ------------------------------------------------------------------- |
| `STX_EMAIL`         | Email for login (see [Authentication](/sdks/python/authentication)) |
| `STX_PASSWORD`      | Password for login                                                  |
| `STX_ENV`           | Default `env` if kwarg is not set                                   |
| `STX_REGION`        | Default `region` if kwarg is not set                                |
| `STX_PROFILE`       | Default profile name for `~/.stx/credentials`                       |
| `STX_HOST`          | Overrides region/env — useful for local dev                         |
| `STX_SCHEMA_SOURCE` | `"bundled"` (default), `"latest"`, or a URL                         |

Empty strings are treated as **unset**, not as `False` / `""` — so `STX_EMAIL=` in an unset env file won't shadow a profile value.

## Profile files

`~/.stx/credentials` uses the same INI format as `~/.aws/credentials`:

```ini theme={null}
[default]
region   = ontario
env      = staging
email    = you@example.com
password = your-password

[prod-bot]
region   = ontario
env      = production
email    = bot@example.com
password = bot-password

[local]
host     = http://localhost:4000
email    = dev@example.com
password = dev
```

Select a profile at client construction:

```python theme={null}
STX()                            # uses [default]
STX(profile="prod-bot")          # uses [prod-bot]
STX(profile="local")             # uses [local]
```

<Tip>
  Set permissions to `0600` so only your user account can read the file:

  ```bash theme={null}
  chmod 600 ~/.stx/credentials
  ```
</Tip>

## Schema pinning

The SDK's field `Selection`s are validated against a GraphQL schema. You control where that schema comes from.

<Tabs>
  <Tab title="Bundled (default)">
    The schema ships with the SDK — byte-for-byte what was on staging at release time. Predictable, testable, no network dependency at client init.

    ```python theme={null}
    STX(region="ontario", env="production")   # schema_source="bundled" is the default
    ```

    If the server is running a newer schema, the SDK logs a one-time warning pointing you at `pip install --upgrade stx-python`. Existing calls keep working — only calls to fields that don't exist in the bundled schema will raise.
  </Tab>

  <Tab title="Latest">
    Fetch the schema from the server on client construction. Always up-to-date; adds one HTTPS round-trip per client instance.

    ```python theme={null}
    STX(region="ontario", env="production", schema_source="latest")
    ```

    Cached on disk at `~/.stx/cache/schema/<env>/<version>.graphql` so subsequent instances reuse the download. Clear the cache with `rm -rf ~/.stx/cache/schema`.
  </Tab>

  <Tab title="Custom URL">
    Pin to a specific schema file — useful for replaying against a historical release.

    ```python theme={null}
    STX(
        region="ontario", env="production",
        schema_source="https://cdn.sportsxapp.com/schemas/v3.0.51.graphql",
    )
    ```
  </Tab>
</Tabs>

## Default field selection

By default every GraphQL call returns all scalar fields — the SDK walks the return type and requests them for you. Override the default for every call on a given client:

```python theme={null}
from stx import STX, Selection

client = STX(
    region="ontario", env="production",
    default_fields=Selection("market_id", "status"),
)

client.markets()                                    # returns just marketId + status
client.markets(selections=Selection("title"))       # per-call overrides the default
```

See [Presets](/sdks/python/markets#presets) for canned selections.

## Retry policy

All GraphQL calls are wrapped in a `RetryPolicy` with exponential backoff + decorrelated jitter. Override per-client:

```python theme={null}
from stx import STX
from stx._retry import RetryPolicy

STX(
    region="ontario", env="production",
    retry=RetryPolicy(max_attempts=5, initial_backoff=0.25, jitter=True),
)
```

Disable retries entirely:

```python theme={null}
from stx._retry import RetryPolicy

STX(region="ontario", env="production", retry=RetryPolicy.DISABLED)
```

See [Errors & retries](/sdks/python/errors-and-retries) for the full policy.

## Logging

The SDK uses the standard `logging` module under the `stx` logger:

```python theme={null}
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger("stx").setLevel(logging.DEBUG)
```

* `INFO`: login, token refresh, WS reconnect events.
* `DEBUG`: every GraphQL operation name, WS frame direction, retry attempts.
* `WARNING`: schema version skew, backoff exhaustion.

Sensitive values (passwords, full JWTs) are never logged — only redacted previews.

## Full-example `~/.stx/credentials`

```ini theme={null}
[default]
region   = ontario
env      = staging
email    = dev@example.com
password = dev-password

[prod-readonly]
region   = ontario
env      = production
email    = readonly@example.com
password = readonly-password

[prod-bot]
region   = ontario
env      = production
email    = bot-trader@example.com
password = bot-password
```

```python theme={null}
STX()                             # dev staging
STX(profile="prod-readonly")      # prod, read-only account
STX(profile="prod-bot")           # prod, trading account
```