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.
- elfa_sdk-3.0.0/LICENSE +21 -0
- elfa_sdk-3.0.0/PKG-INFO +276 -0
- elfa_sdk-3.0.0/README.md +234 -0
- elfa_sdk-3.0.0/elfa/__init__.py +41 -0
- elfa_sdk-3.0.0/elfa/client/__init__.py +15 -0
- elfa_sdk-3.0.0/elfa/client/_params.py +202 -0
- elfa_sdk-3.0.0/elfa/client/async_client.py +240 -0
- elfa_sdk-3.0.0/elfa/client/auto_client.py +421 -0
- elfa_sdk-3.0.0/elfa/client/base.py +64 -0
- elfa_sdk-3.0.0/elfa/client/elfa_client.py +246 -0
- elfa_sdk-3.0.0/elfa/client/trade_client.py +177 -0
- elfa_sdk-3.0.0/elfa/exceptions/__init__.py +31 -0
- elfa_sdk-3.0.0/elfa/exceptions/base.py +187 -0
- elfa_sdk-3.0.0/elfa/models/__init__.py +139 -0
- elfa_sdk-3.0.0/elfa/models/auto.py +172 -0
- elfa_sdk-3.0.0/elfa/models/base.py +9 -0
- elfa_sdk-3.0.0/elfa/models/chat.py +29 -0
- elfa_sdk-3.0.0/elfa/models/elfa.py +201 -0
- elfa_sdk-3.0.0/elfa/models/trade.py +86 -0
- elfa_sdk-3.0.0/elfa/utils/__init__.py +16 -0
- elfa_sdk-3.0.0/elfa/utils/hmac.py +32 -0
- elfa_sdk-3.0.0/elfa/utils/http.py +221 -0
- elfa_sdk-3.0.0/elfa/utils/serialize.py +52 -0
- elfa_sdk-3.0.0/elfa/utils/sse.py +69 -0
- elfa_sdk-3.0.0/elfa/version.py +3 -0
- elfa_sdk-3.0.0/elfa_sdk.egg-info/PKG-INFO +276 -0
- elfa_sdk-3.0.0/elfa_sdk.egg-info/SOURCES.txt +40 -0
- elfa_sdk-3.0.0/elfa_sdk.egg-info/dependency_links.txt +1 -0
- elfa_sdk-3.0.0/elfa_sdk.egg-info/requires.txt +14 -0
- elfa_sdk-3.0.0/elfa_sdk.egg-info/top_level.txt +1 -0
- elfa_sdk-3.0.0/pyproject.toml +138 -0
- elfa_sdk-3.0.0/setup.cfg +4 -0
- elfa_sdk-3.0.0/tests/test_auto_client.py +265 -0
- elfa_sdk-3.0.0/tests/test_data_client.py +264 -0
- elfa_sdk-3.0.0/tests/test_errors.py +110 -0
- elfa_sdk-3.0.0/tests/test_hmac.py +37 -0
- elfa_sdk-3.0.0/tests/test_http.py +208 -0
- elfa_sdk-3.0.0/tests/test_live_integration.py +126 -0
- elfa_sdk-3.0.0/tests/test_models.py +57 -0
- elfa_sdk-3.0.0/tests/test_serialize.py +106 -0
- elfa_sdk-3.0.0/tests/test_sse.py +73 -0
- 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.
|
elfa_sdk-3.0.0/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://badge.fury.io/py/elfa-sdk)
|
|
46
|
+
[](https://www.python.org/downloads/)
|
|
47
|
+
[](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).
|
elfa_sdk-3.0.0/README.md
ADDED
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
# Elfa AI Python SDK
|
|
2
|
+
|
|
3
|
+
[](https://badge.fury.io/py/elfa-sdk)
|
|
4
|
+
[](https://www.python.org/downloads/)
|
|
5
|
+
[](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
|
+
]
|