Metadata-Version: 2.4
Name: stablesea
Version: 0.1.0
Summary: Python SDK for the Stable Sea Terminal API
Author: Stable Sea
License: MIT
Project-URL: Homepage, https://stablesea.com
Project-URL: Documentation, https://docs.stablesea.com
Project-URL: Repository, https://github.com/stablesea/stablesea-python
Keywords: stablesea,api,shipping,terminal
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# Stable Sea Python SDK

Official Python client for the [Stable Sea Terminal API](https://stablesea.com), for managing organizations, quotes, orders, and API keys.

## Installation

```bash
pip install stablesea
```

Or install from source:

```bash
pip install /path/to/sdk/python
```

## Quickstart

```python
from stablesea import StableseaClient

# Initialize with your API key (sandbox by default)
client = StableseaClient(api_key="sk_your_api_key")

# List organizations
organizations = client.organizations.list()

# Create an organization
org = client.organizations.create(
    name="Acme Corp",
    contact={"email": "john@acme.com", "first_name": "John", "last_name": "Doe"},
    idempotency_key="unique-key-123",
)

# Create a quote (organization-scoped)
quote = client.quotes.create(
    organization_id="org_01k2cm4r59e5z8k5ggrbbxjcwy",
    offering_id="off_01k4qph5ezfsga7fkvbygsqq93",
    payin_amount="100",
    idempotency_key="quote-key-456",
)

# Create an order from the quote
order = client.orders.create(
    organization_id="org_01k2cm4r59e5z8k5ggrbbxjcwy",
    quote_id=quote["id"],
    idempotency_key="order-key-789",
)

# List API keys
api_keys = client.api_keys.list()

# Create a new API key
new_key = client.api_keys.create(
    name="Production API",
    environment="PRODUCTION",
    permission_level="STANDARD",
)
# Store new_key["api_key"] securely - it's only returned once!

# List liquidity providers
providers = client.liquidity_providers.list()

# Get exchange rate for a provider
rate = client.liquidity_providers.get_exchange_rate("ALPHA")

client.close()
```

## Async Support

For async/await support, use `AsyncStableseaClient`:

```python
import asyncio
from stablesea import AsyncStableseaClient

async def main():
    async with AsyncStableseaClient(api_key="sk_your_api_key") as client:
        orgs = await client.organizations.list()
        quote = await client.quotes.create(
            organization_id="org_...",
            offering_id="off_...",
            payin_amount="100",
            idempotency_key="unique-key",
        )
        print(orgs, quote)

asyncio.run(main())
```

## Configuration

| Parameter   | Default                           | Description                    |
|------------|------------------------------------|--------------------------------|
| `api_key`  | (required)                         | Your Stable Sea API key        |
| `base_url` | `https://api-sandbox.stablesea.com/v1` | API base URL (use production URL for live) |
| `timeout`  | `30.0`                             | Request timeout in seconds     |

## API Resources

| Resource | Methods |
|----------|---------|
| `client.organizations` | `list()`, `create()`, `get()` |
| `client.quotes` | `create()`, `get()` |
| `client.orders` | `create()`, `list()`, `get()` |
| `client.api_keys` | `list()`, `create()`, `rotate()`, `revoke()` |
| `client.liquidity_providers` | `list()`, `get_exchange_rate()` |
| `client.offerings` | `create()`, `get()` |
| `client.external_payment_instruments` | `list()`, `create()`, `get()`, `archive()` |

## Error Handling

```python
from stablesea import StableseaClient, APIError

client = StableseaClient(api_key="sk_...")
try:
    client.organizations.create(...)
except APIError as e:
    print(f"API error {e.status_code}: {e.message}")
```

## License

MIT
