Skip to content

Quickstart

Install

pip install stonepy

Create a client and log on

The client is a context manager. Log on once, then call any resource group; the current session token is attached automatically to endpoints that use session authentication. Refresh can replace the token, and client.session.delete_session(...) clears it.

from stonepy import ClientConfig, StoneXClient
from stonepy.models import ApiLogOnRequestDTO

config = ClientConfig(base_url="https://ciapi.cityindex.com/TradingAPI")

with StoneXClient(config) as client:
    client.session.log_on(
        ApiLogOnRequestDTO(
            UserName="username",
            Password="password",
            AppKey="app-key",
            AppVersion="stonepy",
            AppComments="",
        )
    )
    markets = client.market.list_market_search_paginated(
        "gold",
        search_by_market_code=False,
        search_by_market_name=True,
        spread_product_type=True,
        cfd_product_type=True,
        binary_product_type=False,
        ascending_order=True,
        include_options=False,
        client_account_id=12345,
        page=0,
        page_size=20,
    )
    print(markets.total_number_of_results)

from stonepy import AsyncStoneXClient, ClientConfig
from stonepy.models import ApiLogOnRequestDTO

config = ClientConfig(base_url="https://ciapi.cityindex.com/TradingAPI")

async with AsyncStoneXClient(config) as client:
    await client.session.log_on(
        ApiLogOnRequestDTO(
            UserName="username",
            Password="password",
            AppKey="app-key",
            AppVersion="stonepy",
            AppComments="",
        )
    )
    markets = await client.market.list_market_search_paginated(
        "gold",
        search_by_market_code=False,
        search_by_market_name=True,
        spread_product_type=True,
        cfd_product_type=True,
        binary_product_type=False,
        ascending_order=True,
        include_options=False,
        client_account_id=12345,
        page=0,
        page_size=20,
    )
    print(markets.total_number_of_results)

Use close() for sync clients (or aclose() for async) when you are not using a with block.

Configure from the environment

from stonepy import ClientConfig, StoneXClient

config = ClientConfig.from_env()

with StoneXClient(config) as client:
    ...

ClientConfig.from_env() reads STONEX_BASE_URL, STONEX_APP_KEY, STONEX_USERNAME, and STONEX_PASSWORD. STONEX_BASE_URL is required unless you pass base_url=.

If you supply credentials (directly or via from_env()), the client can refresh the session without an explicit log_on(). Proactive refresh is age-based: it runs when the stored token reaches proactive_refresh_seconds, and no server expiry timestamp is consulted. See Authentication & sessions.

Next steps