elfa-sdk 3.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. elfa_sdk-3.0.0/LICENSE +21 -0
  2. elfa_sdk-3.0.0/PKG-INFO +276 -0
  3. elfa_sdk-3.0.0/README.md +234 -0
  4. elfa_sdk-3.0.0/elfa/__init__.py +41 -0
  5. elfa_sdk-3.0.0/elfa/client/__init__.py +15 -0
  6. elfa_sdk-3.0.0/elfa/client/_params.py +202 -0
  7. elfa_sdk-3.0.0/elfa/client/async_client.py +240 -0
  8. elfa_sdk-3.0.0/elfa/client/auto_client.py +421 -0
  9. elfa_sdk-3.0.0/elfa/client/base.py +64 -0
  10. elfa_sdk-3.0.0/elfa/client/elfa_client.py +246 -0
  11. elfa_sdk-3.0.0/elfa/client/trade_client.py +177 -0
  12. elfa_sdk-3.0.0/elfa/exceptions/__init__.py +31 -0
  13. elfa_sdk-3.0.0/elfa/exceptions/base.py +187 -0
  14. elfa_sdk-3.0.0/elfa/models/__init__.py +139 -0
  15. elfa_sdk-3.0.0/elfa/models/auto.py +172 -0
  16. elfa_sdk-3.0.0/elfa/models/base.py +9 -0
  17. elfa_sdk-3.0.0/elfa/models/chat.py +29 -0
  18. elfa_sdk-3.0.0/elfa/models/elfa.py +201 -0
  19. elfa_sdk-3.0.0/elfa/models/trade.py +86 -0
  20. elfa_sdk-3.0.0/elfa/utils/__init__.py +16 -0
  21. elfa_sdk-3.0.0/elfa/utils/hmac.py +32 -0
  22. elfa_sdk-3.0.0/elfa/utils/http.py +221 -0
  23. elfa_sdk-3.0.0/elfa/utils/serialize.py +52 -0
  24. elfa_sdk-3.0.0/elfa/utils/sse.py +69 -0
  25. elfa_sdk-3.0.0/elfa/version.py +3 -0
  26. elfa_sdk-3.0.0/elfa_sdk.egg-info/PKG-INFO +276 -0
  27. elfa_sdk-3.0.0/elfa_sdk.egg-info/SOURCES.txt +40 -0
  28. elfa_sdk-3.0.0/elfa_sdk.egg-info/dependency_links.txt +1 -0
  29. elfa_sdk-3.0.0/elfa_sdk.egg-info/requires.txt +14 -0
  30. elfa_sdk-3.0.0/elfa_sdk.egg-info/top_level.txt +1 -0
  31. elfa_sdk-3.0.0/pyproject.toml +138 -0
  32. elfa_sdk-3.0.0/setup.cfg +4 -0
  33. elfa_sdk-3.0.0/tests/test_auto_client.py +265 -0
  34. elfa_sdk-3.0.0/tests/test_data_client.py +264 -0
  35. elfa_sdk-3.0.0/tests/test_errors.py +110 -0
  36. elfa_sdk-3.0.0/tests/test_hmac.py +37 -0
  37. elfa_sdk-3.0.0/tests/test_http.py +208 -0
  38. elfa_sdk-3.0.0/tests/test_live_integration.py +126 -0
  39. elfa_sdk-3.0.0/tests/test_models.py +57 -0
  40. elfa_sdk-3.0.0/tests/test_serialize.py +106 -0
  41. elfa_sdk-3.0.0/tests/test_sse.py +73 -0
  42. elfa_sdk-3.0.0/tests/test_trade_client.py +135 -0
elfa_sdk-3.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 Elfa AI
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,276 @@
1
+ Metadata-Version: 2.4
2
+ Name: elfa-sdk
3
+ Version: 3.0.0
4
+ Summary: Official Python SDK for the Elfa API - social intelligence, AI chat, and the Auto/Trade engines for crypto
5
+ Author-email: Elfa AI <support@elfa.ai>
6
+ Maintainer-email: Elfa AI <support@elfa.ai>
7
+ License: MIT
8
+ Project-URL: Homepage, https://elfa.ai
9
+ Project-URL: Documentation, https://docs.elfa.ai
10
+ Project-URL: Repository, https://github.com/elfa-ai/elfa-sdk-python
11
+ Project-URL: Bug Tracker, https://github.com/elfa-ai/elfa-sdk-python/issues
12
+ Keywords: elfa,api,social,intelligence,twitter,telegram,crypto,mentions,narratives,chat,trading
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.9
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
24
+ Classifier: Topic :: Scientific/Engineering :: Information Analysis
25
+ Requires-Python: >=3.9
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Requires-Dist: httpx>=0.24.0
29
+ Requires-Dist: pydantic>=2.0.0
30
+ Requires-Dist: typing-extensions>=4.0.0
31
+ Provides-Extra: dev
32
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
33
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
34
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
35
+ Requires-Dist: respx>=0.20.0; extra == "dev"
36
+ Requires-Dist: black>=23.0.0; extra == "dev"
37
+ Requires-Dist: isort>=5.12.0; extra == "dev"
38
+ Requires-Dist: mypy>=1.0.0; extra == "dev"
39
+ Requires-Dist: flake8>=6.0.0; extra == "dev"
40
+ Requires-Dist: coverage>=7.0.0; extra == "dev"
41
+ Dynamic: license-file
42
+
43
+ # Elfa AI Python SDK
44
+
45
+ [![PyPI version](https://badge.fury.io/py/elfa-sdk.svg)](https://badge.fury.io/py/elfa-sdk)
46
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
47
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
48
+
49
+ Official Python SDK for the Elfa API v2 — social intelligence, AI chat, and the Auto/Trade engines for crypto. Sync and async clients, fully typed with Pydantic.
50
+
51
+ ## Features
52
+
53
+ - **Social intelligence** — trending tokens, mentions, narratives, smart stats, event summaries
54
+ - **AI chat** — market analysis and conversational chat via `client.chat`
55
+ - **Auto condition engine** — build EQL queries that notify or trade via `client.auto`
56
+ - **Direct trading** — place orders and manage positions via `client.trade`
57
+ - **Sync and async** — `ElfaClient` and `AsyncElfaClient`, same surface
58
+ - **Typed** — Pydantic v2 models, full type hints
59
+ - **Robust** — retries with backoff, typed errors, HMAC request signing
60
+
61
+ > The SDK returns processed metadata and tweet links only — never raw tweet content. For raw tweets, call the X (Twitter) API directly using the returned links/ids.
62
+
63
+ ## Installation
64
+
65
+ ```bash
66
+ pip install elfa-sdk
67
+ ```
68
+
69
+ ## Quick start
70
+
71
+ ### Synchronous
72
+
73
+ ```python
74
+ from elfa import ElfaClient
75
+
76
+ client = ElfaClient(api_key="your-api-key")
77
+
78
+ trending = client.get_trending_tokens(time_window="24h")
79
+ for token in trending.data.data:
80
+ print(token.token, token.current_count, f"{token.change_percent:+.1f}%")
81
+
82
+ mentions = client.get_keyword_mentions(keywords="bitcoin,ethereum", time_window="1h")
83
+ for mention in mentions.data:
84
+ print(mention.link, mention.like_count)
85
+
86
+ answer = client.chat("What's the sentiment on Bitcoin today?")
87
+ print(answer.data.message)
88
+ ```
89
+
90
+ ### Asynchronous
91
+
92
+ ```python
93
+ import asyncio
94
+ from elfa import AsyncElfaClient
95
+
96
+ async def main():
97
+ async with AsyncElfaClient(api_key="your-api-key") as client:
98
+ stats = await client.get_account_smart_stats("elonmusk")
99
+ print(stats.data.smart_following_count)
100
+
101
+ asyncio.run(main())
102
+ ```
103
+
104
+ ## Configuration
105
+
106
+ ```python
107
+ client = ElfaClient(
108
+ api_key="your-api-key",
109
+ base_url="https://api.elfa.ai", # default (production)
110
+ timeout=30.0, # per-request timeout, seconds
111
+ retries=3, # retries for idempotent (GET) requests
112
+ retry_delay=1.0, # base delay for exponential backoff
113
+ hmac_secret=None, # required for Auto/Trade mutations (see below)
114
+ headers=None, # extra headers sent on every request
115
+ )
116
+
117
+ # Quick reachability/auth check
118
+ assert client.test_connection() is True
119
+ ```
120
+
121
+ The Auto and Trade engines are also constructable standalone if you only need one:
122
+
123
+ ```python
124
+ from elfa import TradeClient
125
+
126
+ trade = TradeClient(api_key="your-api-key", hmac_secret="your-hmac-secret")
127
+ # ... use trade.place_order(...) etc.
128
+ trade.close()
129
+ ```
130
+
131
+ The API key is sent as the `x-elfa-api-key` header on every request. Read it from the environment in your app:
132
+
133
+ ```python
134
+ import os
135
+ from elfa import ElfaClient
136
+
137
+ client = ElfaClient(api_key=os.environ["ELFA_API_KEY"])
138
+ ```
139
+
140
+ ## Core data & chat
141
+
142
+ All methods exist on both `ElfaClient` (sync) and `AsyncElfaClient` (async).
143
+
144
+ | Method | Endpoint |
145
+ | --- | --- |
146
+ | `ping()` | `/v2/ping` |
147
+ | `get_api_key_status()` | `/v2/key-status` |
148
+ | `get_trending_tokens(...)` | `/v2/aggregations/trending-tokens` |
149
+ | `get_account_smart_stats(username)` | `/v2/account/smart-stats` |
150
+ | `get_keyword_mentions(...)` | `/v2/data/keyword-mentions` |
151
+ | `get_token_news(...)` | `/v2/data/token-news` |
152
+ | `get_trending_cas_twitter(...)` | `/v2/aggregations/trending-cas/twitter` |
153
+ | `get_trending_cas_telegram(...)` | `/v2/aggregations/trending-cas/telegram` |
154
+ | `get_top_mentions(ticker, ...)` | `/v2/data/top-mentions` |
155
+ | `get_event_summary(keywords, ...)` | `/v2/data/event-summary` |
156
+ | `get_trending_narratives(...)` | `/v2/data/trending-narratives` |
157
+ | `chat(message, ...)` | `/v2/chat` |
158
+
159
+ Time-ranged endpoints accept either `time_window="24h"` or both `from_time` and `to_time` (unix seconds).
160
+
161
+ ## Auto condition engine (`client.auto`)
162
+
163
+ Build [EQL](https://docs.elfa.ai) queries that watch conditions and fire actions (notify, webhook, or trade). Notification-only queries need no secret; trade-action queries require an `hmac_secret`.
164
+
165
+ ```python
166
+ query = {
167
+ "query": {
168
+ "conditions": {
169
+ "AND": [{
170
+ "source": "price", "method": "current",
171
+ "args": {"symbol": "BTC", "exchange": "hyperliquid"},
172
+ "operator": ">", "value": 250000,
173
+ }]
174
+ },
175
+ "actions": [{"stepId": "notify", "type": "notify", "params": {"message": "BTC > 250k"}}],
176
+ "expiresIn": "24h",
177
+ },
178
+ "title": "btc breakout alert",
179
+ }
180
+
181
+ client.auto.validate_query(query)
182
+ created = client.auto.create_query(query)
183
+ query_id = created.id or created.query_id
184
+
185
+ status = client.auto.get_query(query_id)
186
+ client.auto.cancel_query(query_id)
187
+ client.auto.delete_query(query_id)
188
+ ```
189
+
190
+ Also available: `chat`, `list_queries`, drafts (`list_drafts`/`get_draft`/`upsert_draft`/`delete_draft`/`validate_draft`/`convert_draft`), `list_sessions`/`get_session`, `list_executions`/`get_execution`, exchanges (`list_exchanges`/`connect_exchange`/`disconnect_exchange`), and `validate_symbol`.
191
+
192
+ ### Streaming notifications (SSE)
193
+
194
+ ```python
195
+ for event in client.auto.stream_query(query_id):
196
+ print(event.event, event.data)
197
+
198
+ # async
199
+ async for event in async_client.auto.stream_all():
200
+ print(event.event, event.data)
201
+ ```
202
+
203
+ ## Direct trading (`client.trade`)
204
+
205
+ Trade a Privy-linked exchange account. All writes require an `hmac_secret`; previews do not execute and are free. **Sizes and prices are decimal strings.**
206
+
207
+ ```python
208
+ client = ElfaClient(api_key="your-api-key", hmac_secret="your-hmac-secret")
209
+
210
+ preview = client.trade.preview_order({
211
+ "exchange": "hyperliquid", "symbol": "BTC",
212
+ "side": "buy", "orderType": "market", "size": "0.001",
213
+ })
214
+
215
+ if preview.would_execute:
216
+ result = client.trade.place_order({
217
+ "exchange": "hyperliquid", "symbol": "BTC",
218
+ "side": "buy", "orderType": "market", "size": "0.001",
219
+ })
220
+ print(result.order_id, result.filled_size, result.avg_fill_price)
221
+ ```
222
+
223
+ Methods: `preview_order`, `place_order`, `cancel_order`, `modify_order`, `preview_close_position`, `close_position`, `preview_set_position_tpsl`, `set_position_tpsl`.
224
+
225
+ ## HMAC signing
226
+
227
+ Auto trade-action queries and all `client.trade` writes are signed when `hmac_secret` is set. The SDK builds the signature over `timestamp + METHOD + mounted_path + body` and sends `x-elfa-timestamp` and `x-elfa-signature` headers. Signing every mutation is safe, so passing `hmac_secret` is always fine. Generate a secret in the [dev portal](https://docs.elfa.ai).
228
+
229
+ ## Error handling
230
+
231
+ ```python
232
+ from elfa import (
233
+ ElfaAPIError,
234
+ ElfaAuthenticationError,
235
+ ElfaRateLimitError,
236
+ ElfaValidationError,
237
+ ElfaNetworkError,
238
+ )
239
+
240
+ try:
241
+ client.get_trending_tokens(time_window="24h")
242
+ except ElfaAuthenticationError:
243
+ ... # bad/missing API key
244
+ except ElfaRateLimitError as e:
245
+ print("retry after", e.retry_after, "reset", e.reset_time)
246
+ except ElfaValidationError as e:
247
+ print("invalid params", e.validation_errors)
248
+ except ElfaNetworkError:
249
+ ... # connection problem
250
+ except ElfaAPIError as e:
251
+ print("api error", e.status_code, e)
252
+ ```
253
+
254
+ Idempotent (GET) requests are retried with exponential backoff on network errors, rate limits, and 5xx responses. Mutations are not retried automatically.
255
+
256
+ ## Development
257
+
258
+ ```bash
259
+ git clone https://github.com/elfa-ai/elfa-sdk-python.git
260
+ cd elfa-sdk-python
261
+ pip install -e ".[dev]"
262
+
263
+ make check # flake8 + mypy + pytest
264
+ make format # black + isort
265
+ ```
266
+
267
+ Live integration tests run only when `ELFA_API_KEY` is set (optionally `ELFA_BASE_URL`, `ELFA_HMAC_SECRET`); otherwise they skip.
268
+
269
+ ## Support
270
+
271
+ - [Documentation](https://docs.elfa.ai)
272
+ - [Issues](https://github.com/elfa-ai/elfa-sdk-python/issues)
273
+
274
+ ## License
275
+
276
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,234 @@
1
+ # Elfa AI Python SDK
2
+
3
+ [![PyPI version](https://badge.fury.io/py/elfa-sdk.svg)](https://badge.fury.io/py/elfa-sdk)
4
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+
7
+ Official Python SDK for the Elfa API v2 — social intelligence, AI chat, and the Auto/Trade engines for crypto. Sync and async clients, fully typed with Pydantic.
8
+
9
+ ## Features
10
+
11
+ - **Social intelligence** — trending tokens, mentions, narratives, smart stats, event summaries
12
+ - **AI chat** — market analysis and conversational chat via `client.chat`
13
+ - **Auto condition engine** — build EQL queries that notify or trade via `client.auto`
14
+ - **Direct trading** — place orders and manage positions via `client.trade`
15
+ - **Sync and async** — `ElfaClient` and `AsyncElfaClient`, same surface
16
+ - **Typed** — Pydantic v2 models, full type hints
17
+ - **Robust** — retries with backoff, typed errors, HMAC request signing
18
+
19
+ > The SDK returns processed metadata and tweet links only — never raw tweet content. For raw tweets, call the X (Twitter) API directly using the returned links/ids.
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ pip install elfa-sdk
25
+ ```
26
+
27
+ ## Quick start
28
+
29
+ ### Synchronous
30
+
31
+ ```python
32
+ from elfa import ElfaClient
33
+
34
+ client = ElfaClient(api_key="your-api-key")
35
+
36
+ trending = client.get_trending_tokens(time_window="24h")
37
+ for token in trending.data.data:
38
+ print(token.token, token.current_count, f"{token.change_percent:+.1f}%")
39
+
40
+ mentions = client.get_keyword_mentions(keywords="bitcoin,ethereum", time_window="1h")
41
+ for mention in mentions.data:
42
+ print(mention.link, mention.like_count)
43
+
44
+ answer = client.chat("What's the sentiment on Bitcoin today?")
45
+ print(answer.data.message)
46
+ ```
47
+
48
+ ### Asynchronous
49
+
50
+ ```python
51
+ import asyncio
52
+ from elfa import AsyncElfaClient
53
+
54
+ async def main():
55
+ async with AsyncElfaClient(api_key="your-api-key") as client:
56
+ stats = await client.get_account_smart_stats("elonmusk")
57
+ print(stats.data.smart_following_count)
58
+
59
+ asyncio.run(main())
60
+ ```
61
+
62
+ ## Configuration
63
+
64
+ ```python
65
+ client = ElfaClient(
66
+ api_key="your-api-key",
67
+ base_url="https://api.elfa.ai", # default (production)
68
+ timeout=30.0, # per-request timeout, seconds
69
+ retries=3, # retries for idempotent (GET) requests
70
+ retry_delay=1.0, # base delay for exponential backoff
71
+ hmac_secret=None, # required for Auto/Trade mutations (see below)
72
+ headers=None, # extra headers sent on every request
73
+ )
74
+
75
+ # Quick reachability/auth check
76
+ assert client.test_connection() is True
77
+ ```
78
+
79
+ The Auto and Trade engines are also constructable standalone if you only need one:
80
+
81
+ ```python
82
+ from elfa import TradeClient
83
+
84
+ trade = TradeClient(api_key="your-api-key", hmac_secret="your-hmac-secret")
85
+ # ... use trade.place_order(...) etc.
86
+ trade.close()
87
+ ```
88
+
89
+ The API key is sent as the `x-elfa-api-key` header on every request. Read it from the environment in your app:
90
+
91
+ ```python
92
+ import os
93
+ from elfa import ElfaClient
94
+
95
+ client = ElfaClient(api_key=os.environ["ELFA_API_KEY"])
96
+ ```
97
+
98
+ ## Core data & chat
99
+
100
+ All methods exist on both `ElfaClient` (sync) and `AsyncElfaClient` (async).
101
+
102
+ | Method | Endpoint |
103
+ | --- | --- |
104
+ | `ping()` | `/v2/ping` |
105
+ | `get_api_key_status()` | `/v2/key-status` |
106
+ | `get_trending_tokens(...)` | `/v2/aggregations/trending-tokens` |
107
+ | `get_account_smart_stats(username)` | `/v2/account/smart-stats` |
108
+ | `get_keyword_mentions(...)` | `/v2/data/keyword-mentions` |
109
+ | `get_token_news(...)` | `/v2/data/token-news` |
110
+ | `get_trending_cas_twitter(...)` | `/v2/aggregations/trending-cas/twitter` |
111
+ | `get_trending_cas_telegram(...)` | `/v2/aggregations/trending-cas/telegram` |
112
+ | `get_top_mentions(ticker, ...)` | `/v2/data/top-mentions` |
113
+ | `get_event_summary(keywords, ...)` | `/v2/data/event-summary` |
114
+ | `get_trending_narratives(...)` | `/v2/data/trending-narratives` |
115
+ | `chat(message, ...)` | `/v2/chat` |
116
+
117
+ Time-ranged endpoints accept either `time_window="24h"` or both `from_time` and `to_time` (unix seconds).
118
+
119
+ ## Auto condition engine (`client.auto`)
120
+
121
+ Build [EQL](https://docs.elfa.ai) queries that watch conditions and fire actions (notify, webhook, or trade). Notification-only queries need no secret; trade-action queries require an `hmac_secret`.
122
+
123
+ ```python
124
+ query = {
125
+ "query": {
126
+ "conditions": {
127
+ "AND": [{
128
+ "source": "price", "method": "current",
129
+ "args": {"symbol": "BTC", "exchange": "hyperliquid"},
130
+ "operator": ">", "value": 250000,
131
+ }]
132
+ },
133
+ "actions": [{"stepId": "notify", "type": "notify", "params": {"message": "BTC > 250k"}}],
134
+ "expiresIn": "24h",
135
+ },
136
+ "title": "btc breakout alert",
137
+ }
138
+
139
+ client.auto.validate_query(query)
140
+ created = client.auto.create_query(query)
141
+ query_id = created.id or created.query_id
142
+
143
+ status = client.auto.get_query(query_id)
144
+ client.auto.cancel_query(query_id)
145
+ client.auto.delete_query(query_id)
146
+ ```
147
+
148
+ Also available: `chat`, `list_queries`, drafts (`list_drafts`/`get_draft`/`upsert_draft`/`delete_draft`/`validate_draft`/`convert_draft`), `list_sessions`/`get_session`, `list_executions`/`get_execution`, exchanges (`list_exchanges`/`connect_exchange`/`disconnect_exchange`), and `validate_symbol`.
149
+
150
+ ### Streaming notifications (SSE)
151
+
152
+ ```python
153
+ for event in client.auto.stream_query(query_id):
154
+ print(event.event, event.data)
155
+
156
+ # async
157
+ async for event in async_client.auto.stream_all():
158
+ print(event.event, event.data)
159
+ ```
160
+
161
+ ## Direct trading (`client.trade`)
162
+
163
+ Trade a Privy-linked exchange account. All writes require an `hmac_secret`; previews do not execute and are free. **Sizes and prices are decimal strings.**
164
+
165
+ ```python
166
+ client = ElfaClient(api_key="your-api-key", hmac_secret="your-hmac-secret")
167
+
168
+ preview = client.trade.preview_order({
169
+ "exchange": "hyperliquid", "symbol": "BTC",
170
+ "side": "buy", "orderType": "market", "size": "0.001",
171
+ })
172
+
173
+ if preview.would_execute:
174
+ result = client.trade.place_order({
175
+ "exchange": "hyperliquid", "symbol": "BTC",
176
+ "side": "buy", "orderType": "market", "size": "0.001",
177
+ })
178
+ print(result.order_id, result.filled_size, result.avg_fill_price)
179
+ ```
180
+
181
+ Methods: `preview_order`, `place_order`, `cancel_order`, `modify_order`, `preview_close_position`, `close_position`, `preview_set_position_tpsl`, `set_position_tpsl`.
182
+
183
+ ## HMAC signing
184
+
185
+ Auto trade-action queries and all `client.trade` writes are signed when `hmac_secret` is set. The SDK builds the signature over `timestamp + METHOD + mounted_path + body` and sends `x-elfa-timestamp` and `x-elfa-signature` headers. Signing every mutation is safe, so passing `hmac_secret` is always fine. Generate a secret in the [dev portal](https://docs.elfa.ai).
186
+
187
+ ## Error handling
188
+
189
+ ```python
190
+ from elfa import (
191
+ ElfaAPIError,
192
+ ElfaAuthenticationError,
193
+ ElfaRateLimitError,
194
+ ElfaValidationError,
195
+ ElfaNetworkError,
196
+ )
197
+
198
+ try:
199
+ client.get_trending_tokens(time_window="24h")
200
+ except ElfaAuthenticationError:
201
+ ... # bad/missing API key
202
+ except ElfaRateLimitError as e:
203
+ print("retry after", e.retry_after, "reset", e.reset_time)
204
+ except ElfaValidationError as e:
205
+ print("invalid params", e.validation_errors)
206
+ except ElfaNetworkError:
207
+ ... # connection problem
208
+ except ElfaAPIError as e:
209
+ print("api error", e.status_code, e)
210
+ ```
211
+
212
+ Idempotent (GET) requests are retried with exponential backoff on network errors, rate limits, and 5xx responses. Mutations are not retried automatically.
213
+
214
+ ## Development
215
+
216
+ ```bash
217
+ git clone https://github.com/elfa-ai/elfa-sdk-python.git
218
+ cd elfa-sdk-python
219
+ pip install -e ".[dev]"
220
+
221
+ make check # flake8 + mypy + pytest
222
+ make format # black + isort
223
+ ```
224
+
225
+ Live integration tests run only when `ELFA_API_KEY` is set (optionally `ELFA_BASE_URL`, `ELFA_HMAC_SECRET`); otherwise they skip.
226
+
227
+ ## Support
228
+
229
+ - [Documentation](https://docs.elfa.ai)
230
+ - [Issues](https://github.com/elfa-ai/elfa-sdk-python/issues)
231
+
232
+ ## License
233
+
234
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,41 @@
1
+ """
2
+ Elfa AI Python SDK
3
+
4
+ Official Python SDK for the Elfa API — social intelligence, AI chat, and the
5
+ Auto/Trade engines for crypto.
6
+ """
7
+
8
+ from elfa.client.async_client import AsyncElfaClient
9
+ from elfa.client.auto_client import AsyncAutoClient, AutoClient
10
+ from elfa.client.elfa_client import ElfaClient
11
+ from elfa.client.trade_client import AsyncTradeClient, TradeClient
12
+ from elfa.exceptions import (
13
+ ElfaAPIError,
14
+ ElfaAuthenticationError,
15
+ ElfaNetworkError,
16
+ ElfaNotFoundError,
17
+ ElfaRateLimitError,
18
+ ElfaTimeoutError,
19
+ ElfaValidationError,
20
+ )
21
+ from elfa.version import VERSION as __version__
22
+
23
+ __author__ = "Elfa AI"
24
+ __email__ = "support@elfa.ai"
25
+
26
+ __all__ = [
27
+ "ElfaClient",
28
+ "AsyncElfaClient",
29
+ "AutoClient",
30
+ "AsyncAutoClient",
31
+ "TradeClient",
32
+ "AsyncTradeClient",
33
+ "ElfaAPIError",
34
+ "ElfaAuthenticationError",
35
+ "ElfaRateLimitError",
36
+ "ElfaNotFoundError",
37
+ "ElfaValidationError",
38
+ "ElfaNetworkError",
39
+ "ElfaTimeoutError",
40
+ "__version__",
41
+ ]
@@ -0,0 +1,15 @@
1
+ """Elfa SDK client classes."""
2
+
3
+ from elfa.client.async_client import AsyncElfaClient
4
+ from elfa.client.auto_client import AsyncAutoClient, AutoClient
5
+ from elfa.client.elfa_client import ElfaClient
6
+ from elfa.client.trade_client import AsyncTradeClient, TradeClient
7
+
8
+ __all__ = [
9
+ "ElfaClient",
10
+ "AsyncElfaClient",
11
+ "AutoClient",
12
+ "AsyncAutoClient",
13
+ "TradeClient",
14
+ "AsyncTradeClient",
15
+ ]