# Talarion SDK

Trade against language models on custom prediction markets. This is the official Python client for the [Talarion](https://talarion.tech) API — async, typed, and ready to roll.

## Installation

```bash
pip install talarion
```

Everything's included — async API client, EOA transaction builders, the works. Requires Python 3.10+.

## Quick Start

```python
import asyncio
from datetime import datetime, timezone, timedelta
from talarion import TalarionClient

async def main():
    async with TalarionClient(api_key="tlrn_...") as client:
        # Spin up a brand new prediction market
        instrument = await client.generate_instrument(
            query="Will BTC hit 100k?",
            resolution_time=datetime.now(timezone.utc) + timedelta(days=7),
        )

        # Get a price quote
        quote = await client.get_quote(
            instrument.instrument_id,
            buy_yes=True,
            amount=10.0,
            user_id="user-123",
        )
        print(f"Price: {quote.price}, Amount: {quote.amount}")

asyncio.run(main())
```

That's it. You just created a market and got a quote. Our proprietary mm is on the other side.

## EOA Direct Interaction

For EOA wallets that skip the Safe/relay flow and talk to the Escrow contract directly. All defaults point at Polygon mainnet — zero config needed:

```python
import asyncio
from talarion import TalarionClient
from talarion.eoa import build_approve_usdc_tx, build_create_trade_tx, sign_and_send

RPC = "https://polygon-rpc.com"
PK = "0xYourPrivateKey"
EOA = "0xYourWalletAddress"

# One-time USDC approval (defaults to Polygon USDC + Talarion Escrow)
approve_tx = build_approve_usdc_tx()
sign_and_send(approve_tx, PK, RPC)

async def main():
    async with TalarionClient(api_key="tlrn_...") as client:
        # Submit an order — for EOAs, operation_sequence comes back as None
        result = await client.submit_order(
            instrument_id="instr_abc123",
            user_id="user-123",
            caller_address=EOA,
            amount=10.0,
            price=0.65,
            buy_yes=True,
        )

        # Build the on-chain tx from the submit result and fire it off
        trade_tx = build_create_trade_tx(result)
        tx_hash = sign_and_send(trade_tx, PK, RPC)
        print(f"Trade created: {tx_hash}")

asyncio.run(main())
```

## Docs

Full reference with examples, type definitions, and the EOA module API lives at **[docs.talarion.tech/sdk](https://docs.talarion.tech/sdk/overview)**.

## License

MIT
