{"id":51091089,"url":"https://github.com/makeev/alphai-sdk","last_synced_at":"2026-06-24T02:01:24.651Z","repository":{"id":364698717,"uuid":"1268902860","full_name":"makeev/alphai-sdk","owner":"makeev","description":"Typed Python client for the AlphaAI.io financial-news REST API","archived":false,"fork":false,"pushed_at":"2026-06-14T05:50:25.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T06:24:26.234Z","etag":null,"topics":["ai-agents","alphai","api-client","financial-news","market-data","mcp","news-api","python","sdk","sec-form-4","stock-market","trading"],"latest_commit_sha":null,"homepage":"https://alphai.io/developers","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/makeev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T04:22:30.000Z","updated_at":"2026-06-14T05:50:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/makeev/alphai-sdk","commit_stats":null,"previous_names":["makeev/alphai-sdk"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/makeev/alphai-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/makeev","download_url":"https://codeload.github.com/makeev/alphai-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeev%2Falphai-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34713791,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","alphai","api-client","financial-news","market-data","mcp","news-api","python","sdk","sec-form-4","stock-market","trading"],"created_at":"2026-06-24T02:01:23.012Z","updated_at":"2026-06-24T02:01:24.645Z","avatar_url":"https://github.com/makeev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# alphai-sdk\n\nTyped Python client for the [AlphaAI](https://alphai.io) financial-news REST API\n— relevance-scored, ticker-linked news and SEC Form 4 insider data, built for AI\nagents and trading bots.\n\n- **Sync and async** clients (`Client` / `AsyncClient`) over `httpx`\n- **Pydantic v2** response models — autocomplete, validation, `Decimal` money\n- **Cursor auto-pagination**, automatic retry on 429/5xx, rate-limit inspection\n- **Typed errors** and full coverage of the 9 public endpoints\n\nAPI reference: \u003chttps://api.alphai.io/api/schema/\u003e · Developer guide:\n\u003chttps://alphai.io/developers\u003e\n\n## Install\n\n```bash\npip install alphai-sdk\n```\n\nRequires Python 3.10+. The import name is `alphai`.\n\n## Authentication\n\nCreate an API key at \u003chttps://alphai.io/account/api-keys\u003e, then pass it\nexplicitly or via the `ALPHAI_API_KEY` environment variable.\n\n```python\nfrom alphai import Client\n\n# reads $ALPHAI_API_KEY when api_key is omitted\nwith Client(api_key=\"ak_live_…\") as client:\n    page = client.news.list(symbol=\"NVDA\")\n    for article in page.results:\n        print(article.title, \"→\", article.relevance_score)\n```\n\nRate limits are per account, per hour: **Free 100 · Basic 1,000 · Pro 10,000**.\n\n## Quickstart\n\n### List \u0026 filter the feed\n\n```python\nfrom alphai import Client, NewsCategory\n\nwith Client() as client:\n    page = client.news.list(\n        symbol=\"NVDA\",\n        category=[NewsCategory.EARNINGS, \"insider\"],   # enum or str; OR-matched\n        min_relevance=7,\n        collapse_stories=True,                          # dedupe syndicated reprints\n    )\n    print(page.next_cursor)        # opaque cursor for the next (older) page\n    print(page.has_more)\n```\n\n### Auto-paginate\n\n`iter()` follows the cursor for you and flattens articles across pages:\n\n```python\nwith Client() as client:\n    for article in client.news.iter(category=\"earnings\", max_items=100):\n        print(article.uid, article.title)\n```\n\n### Single article, trending, related, insider\n\n```python\nwith Client() as client:\n    client.news.trending()                 # top ≤10 from the last 48h\n    art = client.news.get(\"788e477c66f3849b\")\n    client.news.related(art.uid)           # up to 6 related articles\n    client.news.insider(symbol=\"NVDA\")     # SEC Form 4 feed (or .insider_iter())\n```\n\n### Symbols \u0026 rollups\n\n```python\nfrom decimal import Decimal\n\nwith Client() as client:\n    client.symbols.list(limit=100)               # active tickers (bare list)\n    nvda = client.symbols.get(\"NVDA\")            # detail (404 if unknown)\n    btc = client.symbols.get(\"BTC-USD\")          # crypto + foreign listings too\n    # Multi-market: .asset_type (\"Stock\"/\"ETF\"/\"Crypto\"), .country, .currency,\n    # .supports_insider (US SEC names only). Crypto is \"\u003cSYM\u003e-USD\"; foreign uses\n    # the Yahoo suffix (e.g. \"VOD.L\").\n    sent = client.symbols.sentiment_summary(\"NVDA\")   # 7-day AI sentiment\n    ins = client.symbols.insider_summary(\"NVDA\")      # 30-day Form 4 rollup\n    assert isinstance(ins.buy_value_usd, Decimal | None)   # money is Decimal\n```\n\n### Async\n\nEvery method mirrors the sync client with `await`; `iter()` is an async generator:\n\n```python\nimport asyncio\nfrom alphai import AsyncClient\n\nasync def main() -\u003e None:\n    async with AsyncClient() as client:\n        async for article in client.news.iter(symbol=\"NVDA\", max_items=20):\n            print(article.title)\n\nasyncio.run(main())\n```\n\n## Example projects\n\n- [**alphai-news-to-email**](https://github.com/makeev/alphai-news-to-email) —\n  a small, deployable app that emails you a deduplicated digest of high-relevance\n  news for your watchlist. Built entirely on this SDK.\n\n## Errors\n\nAll errors derive from `AlphaAIError`:\n\n```python\nfrom alphai import Client, RateLimitError, NotFoundError, AuthenticationError\n\nwith Client() as client:\n    try:\n        client.symbols.get(\"ZZZZ\")\n    except NotFoundError:\n        ...\n    except RateLimitError as e:\n        print(\"retry after\", e.retry_after, \"seconds; limit\", e.limit)\n    except AuthenticationError:\n        ...\n```\n\n| Status | Exception |\n|--------|-----------|\n| 400 | `BadRequestError` (`.fields` for validation errors) |\n| 401 | `AuthenticationError` |\n| 403 | `PermissionDeniedError` |\n| 404 | `NotFoundError` |\n| 429 | `RateLimitError` (`.retry_after`, `.limit`, `.remaining`, `.reset`) |\n| 5xx | `ServerError` |\n| network/timeout | `APIConnectionError` |\n| 2xx, unparseable body | `InvalidResponseError` |\n\nGET requests are automatically retried on 429 / 5xx / connection errors\n(`max_retries`, default 2) with jittered backoff that honors `Retry-After` (capped\nat `max_retry_after`, default 60s, so a bad value can't freeze your process). A\n2xx with a non-JSON / empty body raises `InvalidResponseError`.\n\n## Rate-limit budget\n\nEvery keyed response carries the `X-RateLimit-*` trio. The last one seen is on\nthe client:\n\n```python\nwith Client() as client:\n    client.news.list()\n    rl = client.last_rate_limit\n    if rl:\n        print(f\"{rl.remaining}/{rl.limit} left, resets at {rl.reset}\")\n```\n\n## Configuration\n\n```python\nClient(\n    api_key=None,                       # else $ALPHAI_API_KEY\n    base_url=\"https://api.alphai.io\",   # API host\n    timeout=30.0,\n    max_retries=2,                      # clamped to \u003e= 0\n    backoff_factor=0.5,\n    max_retry_after=60.0,               # cap on honored Retry-After (seconds)\n    user_agent=\"alphai-sdk-python/\u003cversion\u003e\",\n    http_client=None,                   # bring your own httpx.Client (advanced)\n)\n```\n\nThe same keyword arguments apply to `AsyncClient`. When you pass a custom\n`http_client`, the SDK **still applies its `Authorization` header and base URL on\nevery request** — your client just supplies the transport (proxies, custom\ntimeout, mounts). You own its lifecycle (the SDK won't close a client you passed in).\n\n## Development\n\n```bash\nuv venv \u0026\u0026 uv pip install -e \".[dev]\"\nruff check . \u0026\u0026 ruff format --check .\nmypy src/alphai\npytest                       # offline suite\npytest -m integration        # live tests (needs ALPHAI_API_KEY)\n```\n\n## License\n\nMIT — see [LICENSE](LICENSE). API access still requires a valid key.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakeev%2Falphai-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmakeev%2Falphai-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakeev%2Falphai-sdk/lists"}