AGuAlpha Python Client (Overseas)

A Python library for accessing the AGuAlpha Investment Platform via the UK (eu-west-1) deployment at https://agualpha.com/api/.

Which package should I use?

• agualpha (this one) — points to https://agualpha.com/api. Use this if you or your customers cannot reach the .cn domain (e.g. clients outside mainland China).
• agualphacn — points to https://www.agualpha.cn/api. Use this for domestic (mainland China) deployments.

Both packages expose the same public API (AGuAlphaClient, AGuAlphaAsyncClient, identical method signatures). Only the default base_url differs.

Installation

pip install agualpha

For async support:

pip install agualpha[async]

For pandas integration:

pip install agualpha[pandas]

Configuration

Set your API key as an environment variable (recommended over passing it in code):

export AGUALPHA_API_KEY="sk-your-api-key-here"

Optional overrides:

# Point the client at a non-default gateway (e.g. staging).
export AGUALPHA_BASE_URL="https://agualpha.com/api"

No credentials other than the API key are required — the gateway handles database access on its side.

Quick Start

Synchronous Usage

from agualpha import AGuAlphaClient

with AGuAlphaClient(api_key="sk-your-api-key-here") as client:
    positions = client.get_positions(start_date="2025-01-01")
    for p in positions.data:
        print(p.date, p.outstanding, p.value)

Asynchronous Usage

import asyncio
from agualpha import AGuAlphaAsyncClient

async def main():
    async with AGuAlphaAsyncClient(api_key="sk-...") as client:
        rows = await client.get_adj_close(
            membership="csi300",
            start_date="2025-01-01",
            end_date="2025-12-31",
        )
        print(f"{len(rows)} rows")

asyncio.run(main())

API Surface

All methods mirror agualphacn exactly. List-returning methods auto-paginate when page=None (the default); pass page=int for a single page.

Each list method has a _dataframe variant (get_csi_weights_dataframe, etc.) that returns a pandas.DataFrame.

CLI

A agualpha console-script is provided for quick one-off queries:

agualpha --api-key sk-... positions --start-date 2025-01-01
agualpha adj-close --membership csi300 --start-date 2025-01-01 --end-date 2025-12-31

License

MIT