Metadata-Version: 2.5
Name: anaxer
Version: 0.2.0
Summary: Official Python SDK for the Anaxer Solana real-time data API.
Project-URL: Repository, https://github.com/Anaxer-v2/anaxer-sdk-python
Project-URL: Homepage, https://anaxer.com
Project-URL: Documentation, https://anaxer.com/docs/sdks
Project-URL: Changelog, https://anaxer.com/docs/changelog
Project-URL: Issues, https://anaxer.com/contact
License-Expression: MIT
License-File: LICENSE
Keywords: api,dex,pumpfun,real-time,sdk,solana,trading,websocket
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.6
Requires-Dist: websockets<14,>=12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: typing-extensions>=4.6; extra == 'dev'
Description-Content-Type: text/markdown

# anaxer

Official Python SDK for the [Anaxer](https://anaxer.com) Solana real-time data API: typed
WebSocket streams and REST reads over the public `/v1` contracts.

```bash
pip install anaxer
```

Requires Python 3.10+. Wire contracts: [WebSocket streams](https://anaxer.com/docs/streams)
and [REST API](https://anaxer.com/docs/rest). Changes: [changelog](https://anaxer.com/docs/changelog).

## Quickstart — async streaming

```python
import asyncio
import anaxer

async def main():
    async with anaxer.connect(api_key="...") as client:
        # Plan limits from the server `connected` frame
        print(client.connected.connections_per_stream)

        async with client.stream("creations", exclude_mayhem=True) as sub:
            async for event in sub:
                print("new launch:", event.symbol, event.mint)
                break

asyncio.run(main())
```

`stream()` returns a `Subscription[T]` handle (async-iterable + async context manager).
Prefer `async with client.stream(...) as sub:` so leaving the block always sends
`unsubscribe`. Bare `async for` / `break` also unsubscribes (via `GeneratorExit`).

### Channels

| Channel | Yields | Filters (keyword-only, snake_case) |
|---|---|---|
| `trades` | `SwapV1` | `sources`, `mints`, `wallets` (≤ 100), `min_volume_usd`, `max_volume_usd`, `sol_only` |
| `transfers` | `TransferV1` | `wallets`, `mints`, `min_volume_usd`, `max_volume_usd`, `direction` (`"in"` / `"out"`, needs `wallets`) |
| `creations` | `CreatedV1` | `sources`, `enriched`, `exclude_mayhem` |
| `graduations` | `GraduatedV1` | `sources`, `exclude_mayhem`, `min_liquidity_sol` |
| `prices` | `PriceUpdateV1` | `sources`, `mints` (SOL, USDC, USDT included) |

A filter the channel does not take (a typo, `direction` on `trades`, `sources` on
`transfers`, …) raises `TypeError` before anything is sent; it is never dropped silently.

```python
async with client.stream(
    "transfers",
    wallets=["5G75aiNzTwpycR5c2AyfcYq2nxFLBYV4fyAjsTAeKihh"],
    direction="out",
) as sub:
    async for t in sub:
        print(t.wallet, "->", t.transfer.to, t.transfer.ui_amount, t.transfer.symbol)
```

### Plan rules

`client.connected` holds the plan limits from the `connected` frame:

| Field | Meaning | Starter | Pro |
|---|---|---|---|
| `connections_per_stream` | live subscriptions per channel | 1 | 2 |
| `trades_requires_mints` / `trades_mint_cap` | `trades` must list `mints`; most `mints` | yes; 25 | no (firehose allowed); 100 |
| `transfers_requires_filter` | `transfers` must list `wallets` or `mints` | yes | no (every transfer) |
| `transfers_wallet_cap` / `transfers_mint_cap` | most `wallets` / `mints` on `transfers` | 100 / 25 | 1,000 / 100 |

Free has `creations` and `graduations` only (`plan_restricted` elsewhere). The three
`transfers_*` fields are `None` when the gateway predates the transfers channel; the SDK
connects either way.

### Trades, legs and symbols

A multi-hop swap (a trade routed through several pools) arrives as **one `SwapV1` per hop**,
all with the same `signature`. Each side (`swap.from_`, `swap.to`) has `mint`, `symbol`,
`amount`, `ui_amount`, `decimals`; `symbol` is `None` until the token is resolved (usually its
first second or two) or when it has no on-chain symbol. Symbols are labels, not identities:
key on `mint`. `transfer.symbol` works the same way. Transfers have **no `source`** field.

### Side-channel errors

Reconnect-triggering / non-fatal codes (e.g. `slow_consumer`) are delivered on
`client.on_error(callback)` and/or `async for err in client.errors` — they never
interrupt an open `Subscription`'s `async for`. Subscription-fatal codes
(`invalid_filters`, `plan_restricted`, `subscription_limit`, …) raise from that subscription
only. `unauthorized` is terminal.

## Quickstart — sync REST

```python
from anaxer import Client

client = Client(api_key="...")
price = client.tokens.price("3PFaeFMXiRVYueDCnHHSKndKDDpKZhbhFjQ13JXYpump")
print(price.price.usd, price.stale)
client.close()
```

`Client` is REST-only — it has no `stream()` method. Use it when you do not want a
WebSocket. `AsyncClient` (from `anaxer.connect`) exposes the same REST surface via `await`.

### REST surface

| Method | Returns |
|---|---|
| `tokens.get(mint)` | `TokenMetadataV1` |
| `tokens.batch(mints)` | `list[TokenMetadataV1]` (up to **50** mints; unknown mints omitted) |
| `tokens.price(mint)` | `RestPriceV1` (the stream price plus `stale`) |
| `tokens.batch_price(mints)` | `list[RestPriceV1]` (up to **100** mints; missing prices omitted) |
| `tokens.trades(mint, ...)` / `iter_trades(mint, ...)` | `Page[SwapV1]`: `mint` on either side |
| `wallets.trades(wallet, ...)` / `wallets.iter_trades(...)` | `Page[SwapV1]`: the wallet's trades |
| `wallets.transfers(wallet, ...)` / `wallets.iter_transfers(...)` | `Page[TransferV1]`: the wallet's transfers, sent and received |
| `creations(...)` / `iter_creations(...)` | `Page[CreatedV1]` |
| `graduations(...)` / `iter_graduations(...)` | `Page[GraduatedV1]` |
| `launchpads.stats(window_hours=...)` | `LaunchpadStatsV1` |

Every list takes `limit` (1–200, default 50), `cursor`, `from_` and `to`, plus:

| Option | `tokens.trades` | `wallets.trades` | `wallets.transfers` | `creations` | `graduations` |
|---|---|---|---|---|---|
| `source` (one) or `sources` (list, ≤ 20) | ✅ | ✅ | — | ✅ | ✅ |
| `mints` (≤ 100) | path | ✅ either side | ✅ | — | — |
| `min_volume_usd` / `max_volume_usd` | ✅ | ✅ | ✅ | — | — |
| `sol_only` | ✅ | ✅ | — | — | — |
| `direction` (`"in"` / `"out"`) | — | — | ✅ | — | — |
| `exclude_mayhem` | — | — | — | ✅ | ✅ |
| `min_liquidity_sol` | — | — | — | — | ✅ |

Options are keyword-only, and an unknown one raises `TypeError` (the API itself answers
`400 invalid_request` for an unknown query parameter). `source` and `sources` are exclusive:
passing both raises `AnaxerError("invalid_request")` before any request. A set volume bound
excludes rows with `volume_usd: None`. Quote assets (SOL, USDC, USDT) are rejected as the
`tokens.trades` mint and in `wallets.trades` `mints`; use `sol_only=True` for SOL-paired
trades. Wallet and mint path parameters are URL-encoded.

List endpoints return a `Page` (`data`, `next`, `window`). Use `iter_*` to walk `next`
across pages. Wire field `from` is exposed in Python as `from_` (reserved word) with a
Pydantic alias so round-trips keep the wire key.

```python
for t in client.wallets.iter_transfers(
    "5G75aiNzTwpycR5c2AyfcYq2nxFLBYV4fyAjsTAeKihh", direction="in", min_volume_usd=100
):
    print(t.transfer.from_, t.transfer.ui_amount, t.transfer.symbol)
```

Auth is always `Authorization: Bearer <api_key>` (same as the TypeScript SDK).
`programs()` is not included.

## Gap recovery after a reconnect

After a disconnect the client reconnects and re-subscribes, but resumes the **live** feed
only — it does not replay the gap for you. Recover it with a REST backfill, then trust the
live stream again. Every event carries a `slot` for on-chain ordering and a `timestamp`
(unix ms, nullable), which is what you page the backfill with.

```python
import time

last_ts = int(time.time() * 1000)

async with client.stream("creations") as sub:
    async for event in sub:
        last_ts = event.timestamp or last_ts   # remember how far you got
        handle(event)

# ...socket dropped and the client reconnected...

# iter_creations walks `next` for you.
async for event in client.iter_creations(from_=last_ts, to=int(time.time() * 1000)):
    handle(event)
```

**Backfill is `from_`/`to` on timestamps** — there is no `since: slot` parameter. Use
`slot` to order events, not to resume.

**Recovery is at-least-once, so `handle()` must be idempotent.** A backfill re-delivers
events you may already hold, several events can share one `slot`, and several trades can
share one `signature`. Deduplicate on these wire fields:

| Channel | Dedup key |
| --- | --- |
| `creations`, `graduations` | `signature` |
| `trades` | `signature` + `wallet` + `source` + `swap.from.mint` + `swap.from.amount` + `swap.to.mint` + `swap.to.amount` |
| `transfers` (one message) | `signature` + `wallet` + `transfer.from` + `transfer.to` + `transfer.mint` + `transfer.amount` |
| `transfers` (one transfer, either side) | the same without `wallet` |
| `prices` | none needed: keep the latest per `mint` (highest `slot`) |

`signature` alone is **not** a trade key (a routed swap is one row per hop), and
`signature` + `wallet` is **not** a transfer key (one transaction can move two tokens for the
same wallet). Watching both ends of a transfer delivers it twice, once per watched `wallet`;
use the second transfers key to collapse those. Don't key on `volume_usd`, `symbol` or
`timestamp`: a backfilled row can differ from the live event there (a `symbol` that was `None`
live is filled in once the token resolves). Two hops or transfers that match on every field
above (same wallets, tokens and raw amounts in one transaction) cannot be told apart from the
wire.

```python
def trade_key(s: anaxer.SwapV1) -> tuple[str, ...]:
    return (s.signature, s.wallet, s.source,
            s.swap.from_.mint, s.swap.from_.amount, s.swap.to.mint, s.swap.to.amount)

def transfer_key(t: anaxer.TransferV1) -> tuple[str, ...]:
    return (t.signature, t.wallet, t.transfer.from_, t.transfer.to,
            t.transfer.mint, t.transfer.amount)
```

### What each channel can recover

History is **7 days on every plan**.

| Channel | Backfill | Reach |
| --- | --- | --- |
| `creations` | `client.iter_creations(from_=..., to=...)` | **Full** |
| `graduations` | `client.iter_graduations(from_=..., to=...)` | **Full** |
| `trades` with `mints` | `client.iter_trades(mint, from_=..., to=...)` per mint | **Full** for those mints |
| `trades` with `wallets` | `client.wallets.iter_trades(wallet, from_=..., to=...)` per wallet | **Full** for those wallets |
| `transfers` with `wallets` | `client.wallets.iter_transfers(wallet, from_=..., to=...)` per wallet (`direction`, `mints` as on the stream) | **Full** for those wallets |
| `trades` / `transfers` with neither | — | **None.** There is no chain-wide backfill, so an unfiltered firehose cannot recover a gap. |
| `prices` | — | **None.** Only the current price is stored (`tokens.price`); there is no price history to replay. |

If you run an unfiltered firehose (or a `mints`-only `transfers` subscription) and
completeness matters, subscribe with `wallets` or trade `mints` so a backfill covers you, or
treat the disconnect window as lossy and reconcile from your own store.

## Config

```python
from anaxer import Reconnect, connect

async with connect(
    api_key="...",
    base_url="https://api.anaxer.com",  # local: http://localhost:3010
    reconnect=Reconnect(base_delay=0.5, max_delay=30.0, max_retries=None),
    heartbeat_interval=15.0,  # 0 disables
    rest_max_retries=2,
) as client:
    ...
```

## Errors

All failures surface as `anaxer.AnaxerError` with `.code`, `.message`, `.status`
(HTTP only), and `.subscription_id` (subscription-fatal WS errors only).

SDK-local codes: `connection_closed`, `timeout`, `invalid_payload` (client-side
parse failure — distinct from the wire's `invalid_message`).

- Transient `429` / `5xx` are retried up to `rest_max_retries` (default 2), honoring
  `Retry-After`; other `4xx` raise immediately.
- A REST read that takes over 10 seconds answers `503 upstream_unavailable`. It is retried
  like any `5xx`, so narrow a slow query (`from_` / `to`, filters) rather than raising retries.
- See [errors](https://anaxer.com/docs/errors) for every code.

## Changes in 0.2.0

- `stream("transfers", ...)` with `direction`; `wallets.trades` / `wallets.transfers` (plus
  `iter_*`) on both clients.
- `sources` lists and `min_volume_usd` / `max_volume_usd` on the list endpoints.
- Unknown keyword filters and options raise `TypeError` (0.1.x dropped some silently,
  `direction` on streams among them).
- `tokens.price` / `batch_price` return `RestPriceV1` (with `stale`).
- `client.connected` gains optional `transfers_requires_filter`, `transfers_wallet_cap`,
  `transfers_mint_cap`.
- Path parameters are URL-encoded; `anaxer.__version__` matches the package version.

Full history: [changelog](https://anaxer.com/docs/changelog).

## Links

- Docs: [anaxer.com/docs/sdks](https://anaxer.com/docs/sdks)
- Source: [github.com/Anaxer-v2/anaxer-sdk-python](https://github.com/Anaxer-v2/anaxer-sdk-python)
- TypeScript sibling: [`@anaxer/sdk`](https://www.npmjs.com/package/@anaxer/sdk)
