carbium 0.1.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.
- carbium-0.1.0/LICENSE +21 -0
- carbium-0.1.0/PKG-INFO +283 -0
- carbium-0.1.0/README.md +249 -0
- carbium-0.1.0/pyproject.toml +68 -0
- carbium-0.1.0/pyproject.toml.orig +46 -0
- carbium-0.1.0/src/carbium/__init__.py +14 -0
- carbium-0.1.0/src/carbium/_account_gen.py +1025 -0
- carbium-0.1.0/src/carbium/_gen.py +1371 -0
- carbium-0.1.0/src/carbium/_geyser/LICENSE +202 -0
- carbium-0.1.0/src/carbium/_geyser/NOTICE +11 -0
- carbium-0.1.0/src/carbium/_geyser/__init__.py +2 -0
- carbium-0.1.0/src/carbium/_geyser/geyser_pb2.py +204 -0
- carbium-0.1.0/src/carbium/_geyser/geyser_pb2.pyi +837 -0
- carbium-0.1.0/src/carbium/_geyser/geyser_pb2_grpc.py +398 -0
- carbium-0.1.0/src/carbium/_geyser/solana_storage_pb2.py +77 -0
- carbium-0.1.0/src/carbium/_geyser/solana_storage_pb2.pyi +261 -0
- carbium-0.1.0/src/carbium/_geyser/solana_storage_pb2_grpc.py +24 -0
- carbium-0.1.0/src/carbium/_http.py +118 -0
- carbium-0.1.0/src/carbium/_version.py +1 -0
- carbium-0.1.0/src/carbium/account.py +121 -0
- carbium-0.1.0/src/carbium/client.py +134 -0
- carbium-0.1.0/src/carbium/dca.py +415 -0
- carbium-0.1.0/src/carbium/errors.py +110 -0
- carbium-0.1.0/src/carbium/py.typed +0 -0
- carbium-0.1.0/src/carbium/retry.py +105 -0
- carbium-0.1.0/src/carbium/stream.py +355 -0
- carbium-0.1.0/src/carbium/tokens.py +172 -0
- carbium-0.1.0/src/carbium/transport.py +330 -0
- carbium-0.1.0/src/carbium/webhooks.py +72 -0
- carbium-0.1.0/src/carbium/ws.py +440 -0
carbium-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Carbium
|
|
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.
|
carbium-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: carbium
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Typed Python client for Carbium's Solana services: RPC, DAS, quote and swap, WebSocket subscriptions, Carbon Stream, webhooks, the account API, DCA and the token API
|
|
5
|
+
Keywords: solana,rpc,das,websocket,yellowstone,grpc,swap,dca,webhooks,carbium
|
|
6
|
+
License-Expression: MIT AND Apache-2.0
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
License-File: src/carbium/_geyser/LICENSE
|
|
9
|
+
License-File: src/carbium/_geyser/NOTICE
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Framework :: AsyncIO
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Dist: httpx>=0.28.1,<0.29
|
|
24
|
+
Requires-Dist: websockets>=17.4,<18
|
|
25
|
+
Requires-Dist: grpcio>=1.85.3,<2 ; extra == 'stream'
|
|
26
|
+
Requires-Dist: protobuf>=7.35.1,<8 ; extra == 'stream'
|
|
27
|
+
Requires-Python: >=3.11
|
|
28
|
+
Project-URL: Homepage, https://carbium.sh
|
|
29
|
+
Project-URL: Documentation, https://carbium.sh/docs
|
|
30
|
+
Project-URL: Repository, https://github.com/carbium-sh/carbium-py
|
|
31
|
+
Project-URL: Issues, https://github.com/carbium-sh/carbium-py/issues
|
|
32
|
+
Provides-Extra: stream
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
|
|
35
|
+
# carbium
|
|
36
|
+
|
|
37
|
+
Typed Python client for Carbium's Solana services on [services.carbium.sh](https://carbium.sh): JSON-RPC (every
|
|
38
|
+
served method, DAS included), quote and swap (`quote`, `swap`, `prices`, `health` and the REST quote), WebSocket
|
|
39
|
+
subscriptions, Carbon Stream (Yellowstone gRPC, an optional extra), the account API, webhook signature checks, the DCA
|
|
40
|
+
API on the dex and the token API. Blocking and asyncio clients. Python 3.11 and newer. Types ship with the package.
|
|
41
|
+
|
|
42
|
+
The package never holds a private key, signs or sends on its own: swap and DCA calls return one unsigned transaction
|
|
43
|
+
for your own wallet to sign, and `send_transaction` takes a transaction you signed, as a string: base58, or base64
|
|
44
|
+
with `encoding` set to `base64`. Every method it offers is served; what the services do not serve is not here.
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
pip install carbium
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Carbon Stream needs the extra: `pip install 'carbium[stream]'`.
|
|
51
|
+
|
|
52
|
+
## Quick start
|
|
53
|
+
|
|
54
|
+
A service key (`c_serv_…`) comes from the dashboard at carbium.sh; put it in `CARBIUM_KEY`. Without one the call
|
|
55
|
+
reaches the door and is refused with 401, which the quick start prints.
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
import os
|
|
59
|
+
|
|
60
|
+
from carbium import Carbium, CarbiumError
|
|
61
|
+
|
|
62
|
+
carbium = Carbium(os.environ.get("CARBIUM_KEY"))
|
|
63
|
+
try:
|
|
64
|
+
answer = carbium.get_latest_blockhash()
|
|
65
|
+
value = answer["value"]
|
|
66
|
+
print("blockhash", value["blockhash"], "valid until block height", value["lastValidBlockHeight"], "at slot", answer["context"]["slot"])
|
|
67
|
+
except CarbiumError as error:
|
|
68
|
+
print(error.kind, error.http_status, error.code, error.reason, error.message)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## RPC, DAS and the quote
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
import os
|
|
75
|
+
|
|
76
|
+
from carbium import AsyncCarbium, Carbium
|
|
77
|
+
|
|
78
|
+
carbium = Carbium(os.environ["CARBIUM_KEY"])
|
|
79
|
+
|
|
80
|
+
# Standard Solana methods take positional params, as on the wire, in snake case.
|
|
81
|
+
balance = carbium.get_balance("So11111111111111111111111111111111111111112")
|
|
82
|
+
accounts = carbium.get_multiple_accounts([a, b], {"encoding": "base64"})
|
|
83
|
+
|
|
84
|
+
# DAS methods take their fields by name.
|
|
85
|
+
asset = carbium.get_asset(id=mint)
|
|
86
|
+
|
|
87
|
+
# Any served method by its wire name.
|
|
88
|
+
slot = carbium.rpc("getSlot", [{"commitment": "confirmed"}])
|
|
89
|
+
|
|
90
|
+
# A JSON-RPC batch: 1 to 100 calls, at most two permit methods, DAS only with DAS.
|
|
91
|
+
results = carbium.batch([("getSlot", []), ("getHealth", [])])
|
|
92
|
+
|
|
93
|
+
# A transaction your own wallet signed, sent as base64. It is never sent twice.
|
|
94
|
+
signature = carbium.send_transaction(signed_base64, {"encoding": "base64"})
|
|
95
|
+
|
|
96
|
+
# The REST quote, GET /cq1/quote: every value of the answer is a string.
|
|
97
|
+
quote = carbium.cq1_quote(SOL, USDC, 100_000_000, 50)
|
|
98
|
+
|
|
99
|
+
# The same calls on asyncio.
|
|
100
|
+
async def latest_slot() -> int:
|
|
101
|
+
async with AsyncCarbium(os.environ["CARBIUM_KEY"]) as client:
|
|
102
|
+
return await client.get_slot()
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Token scans (`getTokenAccountsByOwner`, `getTokenAccountsByDelegate`) are billed by rows, up to 100,005 credits;
|
|
106
|
+
`getProgramAccounts` costs 505; a `getTransactionsForAddress` walk costs 55 plus 50 per upstream call after the first,
|
|
107
|
+
up to 51,255 at `limit` 1000. Name a mint, keep `limit` small, and read the method notes at
|
|
108
|
+
https://carbium.sh/skill.md before running one in a loop.
|
|
109
|
+
|
|
110
|
+
## Errors and retries
|
|
111
|
+
|
|
112
|
+
Every failure is a `CarbiumError`.
|
|
113
|
+
|
|
114
|
+
| Field | Meaning |
|
|
115
|
+
|---|---|
|
|
116
|
+
| `kind` | `auth`, `credits`, `rate_limit`, `request`, `upstream`, `node`, `route`, `transport`, `socket`, `stream`, `account`, `dca`, `tokens`, `webhook` |
|
|
117
|
+
| `http_status` | the HTTP status, 0 when nothing answered |
|
|
118
|
+
| `code` | the JSON-RPC code, an HTTP API's error string, or a close code |
|
|
119
|
+
| `reason` | the door's `error.data.reason`, a close reason, or a gRPC status name |
|
|
120
|
+
| `retryable` | whether waiting and sending the same request can change the answer |
|
|
121
|
+
| `retry_after_ms` | the server's wait hint |
|
|
122
|
+
| `request_id` | `x-request-id`, to quote to support |
|
|
123
|
+
| `data` | `error.data` as served |
|
|
124
|
+
|
|
125
|
+
The RPC client follows the retry policy published in skill.md: it waits the larger of the server's hint
|
|
126
|
+
(`retry-after-ms`, else `retryAfterMs` in the error's data, else `Retry-After`) and 250 ms doubling to 4 s, plus up to
|
|
127
|
+
250 ms of jitter, and tries at most 4 times unless the published row says otherwise. A hint over `max_hint_ms` (30 s
|
|
128
|
+
by default) is not waited for: the error comes back at once with it in `retry_after_ms`. `send_transaction`, 401,
|
|
129
|
+
402 (credits exhausted), 403, bad params (apart from `get_transactions_for_address`'s `-32602` "the walk read no
|
|
130
|
+
history", which is retried), unknown methods and every answer marked `retryable: false` are never retried.
|
|
131
|
+
`Carbium(retry=False)` turns retries off; `max_attempts` lowers the attempt count. The account, DCA and token clients
|
|
132
|
+
never retry: they hand back `retryable` and `retry_after_ms`. Keys, session tokens and webhook secrets never appear
|
|
133
|
+
in error messages, data, reprs or logs.
|
|
134
|
+
|
|
135
|
+
## WebSocket subscriptions (asyncio)
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
import asyncio
|
|
139
|
+
import os
|
|
140
|
+
|
|
141
|
+
from carbium import CarbiumSocket
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
async def main() -> None:
|
|
145
|
+
async with CarbiumSocket(os.environ["CARBIUM_KEY"], on_reseed=lambda info: print("re-read state", info)) as socket:
|
|
146
|
+
sub = socket.account_subscribe(pubkey, lambda n: print(n["context"]["slot"], n["value"]["lamports"]), {"commitment": "confirmed"})
|
|
147
|
+
await sub.ready
|
|
148
|
+
...
|
|
149
|
+
await sub.unsubscribe()
|
|
150
|
+
|
|
151
|
+
asyncio.run(main())
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
All eight served subscriptions have a call (`account_subscribe`, `program_subscribe`, `logs_subscribe`,
|
|
155
|
+
`signature_subscribe`, `slot_subscribe`, `root_subscribe`, `slots_updates_subscribe`, `block_subscribe`). The key
|
|
156
|
+
travels in the `x-api-key` header, never in the address. The client follows the server's close codes: it reconnects
|
|
157
|
+
and binds every live subscription again after 1013, 1012, 1001 and network drops, reconnects once after 1008
|
|
158
|
+
`credits_exhausted`, and stops with `on_fatal` on a key refusal (close 1008 `key_…`, or a handshake refused with 401
|
|
159
|
+
or 403); a handshake refused with 429 waits its `Retry-After`. Nothing is replayed by the
|
|
160
|
+
server after a disconnect: `on_reseed` fires after every reconnect so you re-read what you may have missed
|
|
161
|
+
(`info["gap"]` is true after `stream_gap_reseed_required`). `signature_subscribe` fires once; after a reconnect, check
|
|
162
|
+
`getSignatureStatuses`.
|
|
163
|
+
|
|
164
|
+
## Carbon Stream (Yellowstone gRPC, asyncio)
|
|
165
|
+
|
|
166
|
+
Install the extra beside the package: `pip install 'carbium[stream]'` (grpcio and protobuf; nothing else needs them,
|
|
167
|
+
and `import carbium` never loads them). The key needs the grpc scope and a plan with streams.
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
import os
|
|
171
|
+
|
|
172
|
+
from carbium import CarbiumStream
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
async def main() -> None:
|
|
176
|
+
async with await CarbiumStream.connect(os.environ["CARBIUM_KEY"]) as stream:
|
|
177
|
+
live = stream.subscribe_with_reconnect(
|
|
178
|
+
{"transactions": {"pool": {"account_include": [program_id], "vote": False, "failed": False}}},
|
|
179
|
+
on_update=lambda u: handle(u.transaction) if u.HasField("transaction") else None,
|
|
180
|
+
on_reseed=lambda info: reload_over_rpc(),
|
|
181
|
+
)
|
|
182
|
+
...
|
|
183
|
+
live.close()
|
|
184
|
+
await live.done
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Filters use the proto field names (`accounts`, `slots`, `transactions`, `transactions_status`, `blocks`,
|
|
188
|
+
`blocks_meta`, `entry`, `commitment`, `accounts_data_slice`, `from_slot`), and updates are the Yellowstone
|
|
189
|
+
`SubscribeUpdate` messages. `subscribe_with_reconnect` puts the whole filter set in the first message (a filter change
|
|
190
|
+
needs a new stream), pings every 10 s, retries with the published waits, re-seeds through `on_reseed` on
|
|
191
|
+
`OUT_OF_RANGE`, and resumes from the last slot when the retained floor allows (a resume can replay a slot you already
|
|
192
|
+
saw: dedupe on `(slot, signature)`). It stops on a key, plan, argument or credits refusal and raises it from
|
|
193
|
+
`live.done`. Fields the service refuses (`token_accounts`, cuckoo filters, `include_update_parent`, `block_footer`)
|
|
194
|
+
and a bare transaction filter are caught before any call. The seven unary calls (`get_slot`, `get_block_height`,
|
|
195
|
+
`get_latest_blockhash`, `is_blockhash_valid`, `get_version`, `ping`, `subscribe_replay_info`) are on the same object.
|
|
196
|
+
`on_update` is called, never awaited, and must not block (a reader that takes no frame for 10 s is cut): a coroutine
|
|
197
|
+
function is refused, so hand slow work to your own task or queue. An exception from a handler stops the stream and is
|
|
198
|
+
raised from `live.done`. The key travels as `x-token` metadata; gRPC's
|
|
199
|
+
own `GRPC_TRACE` logging prints metadata, so leave it off while a key is in use. The generated messages come from the
|
|
200
|
+
upstream Yellowstone protos (Apache-2.0): see `carbium/_geyser/NOTICE`.
|
|
201
|
+
|
|
202
|
+
## Webhooks
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
import os
|
|
206
|
+
|
|
207
|
+
from carbium import verify_webhook
|
|
208
|
+
|
|
209
|
+
# in your HTTPS handler, with the RAW body bytes (never a re-encoded JSON string)
|
|
210
|
+
events = verify_webhook(raw_body, request.headers, os.environ["CARBIUM_WEBHOOK_SECRET"])
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Standard Webhooks: HMAC-SHA256 over `webhook-id.webhook-timestamp.body` with the secret's base64 after `whsec_`,
|
|
214
|
+
`v1,` entries in `webhook-signature` (two during a rotation), 300 s of clock tolerance, header names in any case.
|
|
215
|
+
Raises a `CarbiumError` of kind `webhook` with reason `missing_header`, `bad_timestamp`, `stale`, `bad_secret`,
|
|
216
|
+
`no_match` or `bad_json`. Dedupe on `webhook-id`: it stays the same across retries.
|
|
217
|
+
|
|
218
|
+
## Account API
|
|
219
|
+
|
|
220
|
+
An account API key (`c_acct_…`, made on the dashboard) runs the account by API: service keys, webhooks, usage and
|
|
221
|
+
records. Put it in `CARBIUM_ACCOUNT_KEY`.
|
|
222
|
+
|
|
223
|
+
```python
|
|
224
|
+
import os
|
|
225
|
+
|
|
226
|
+
from carbium import CarbiumAccount
|
|
227
|
+
|
|
228
|
+
account = CarbiumAccount(os.environ["CARBIUM_ACCOUNT_KEY"])
|
|
229
|
+
keys = account.keys_list()
|
|
230
|
+
created = account.webhooks_create({"key_id": keys[0]["key_id"], "url": "https://hooks.example.com/carbium", "addresses": [wallet]})
|
|
231
|
+
result = account.webhooks_test(created["webhook"]["webhook_id"]) # read result["outcome"]
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Every operation of the account API has one call, generated from its description, 53 in all. The names are the
|
|
235
|
+
TypeScript SDK's in snake case: `keys_list`, `keys_create`, `keys_rotate`, `webhooks_test`, `usage_daily`,
|
|
236
|
+
`account_balance`, `self`, `activity`, and so on. Path ids are integers. A call that takes a session (made by a
|
|
237
|
+
sign-in) is refused before it is sent when the client holds only an account key: pass `session_token=` for those.
|
|
238
|
+
The public calls (`terms`, `plans`, `signup_challenge`, `pin_start`, `pin_verify`, `wallet_login`) send no
|
|
239
|
+
credential.
|
|
240
|
+
|
|
241
|
+
## DCA API
|
|
242
|
+
|
|
243
|
+
```python
|
|
244
|
+
from carbium import CarbiumDca
|
|
245
|
+
|
|
246
|
+
dca = CarbiumDca()
|
|
247
|
+
quote = dca.quote({"inputMint": USDC, "outputMint": SOL, "amount": "1000000"})
|
|
248
|
+
build = dca.open({"owner": owner, "inputMint": USDC, "outputMint": SOL, "cycles": 10, "amountPerCycle": "1000000", "frequency": "daily"})
|
|
249
|
+
# build["txn_base64"] is unsigned: sign it with the owner's wallet, then send it yourself or relay it:
|
|
250
|
+
sent = dca.send({"txn_base64": signed_base64})
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
Reads: `quote`, `positions`, `history`, `position`, `health`. Builders: `open`, `update`, `withdraw`, `close`. `send`
|
|
254
|
+
relays bytes the owner signed, once. An answer with `ok: false` is an error even at HTTP 200, and the codes
|
|
255
|
+
`rate_limited`, `rate_limited_open`, `rpc_unavailable`, `quote_unavailable` and `door_busy` may be tried again at any
|
|
256
|
+
status. Errors are kind `dca` with the API's `err` string as `code`.
|
|
257
|
+
|
|
258
|
+
## Token API
|
|
259
|
+
|
|
260
|
+
```python
|
|
261
|
+
from carbium import CarbiumTokens
|
|
262
|
+
|
|
263
|
+
tokens = CarbiumTokens()
|
|
264
|
+
sol = tokens.lookup("So11111111111111111111111111111111111111112") # None when the registry does not hold it
|
|
265
|
+
top = tokens.search("", limit=20)
|
|
266
|
+
found = tokens.batch(mints) # 1 to 500 mints
|
|
267
|
+
src = tokens.image_url(mint)
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
Keyless, 300 requests a minute per client. The four public routes: `search`, `lookup` (None until a mint is indexed),
|
|
271
|
+
`batch` (unknown mints are queued by the service) and `image_url` (always answers, with a fallback image).
|
|
272
|
+
|
|
273
|
+
## Limits checked before sending
|
|
274
|
+
|
|
275
|
+
Body 51,200 bytes; a batch holds 1 to 100 calls with at most two permit methods, DAS only with DAS; the scans,
|
|
276
|
+
`getSupply`, `getLargestAccounts`, the fee extras, `getTransactionsForAddress`, `prices`, `health`, `quote` and `swap`
|
|
277
|
+
never batch; a method the services do not serve is refused before it is sent; token `batch` takes up to 500 mints.
|
|
278
|
+
|
|
279
|
+
## Contributing
|
|
280
|
+
|
|
281
|
+
Enable the leak check once per clone: `git config core.hooksPath hooks`.
|
|
282
|
+
|
|
283
|
+
MIT. Docs: https://carbium.sh/docs and https://carbium.sh/skill.md.
|
carbium-0.1.0/README.md
ADDED
|
@@ -0,0 +1,249 @@
|
|
|
1
|
+
# carbium
|
|
2
|
+
|
|
3
|
+
Typed Python client for Carbium's Solana services on [services.carbium.sh](https://carbium.sh): JSON-RPC (every
|
|
4
|
+
served method, DAS included), quote and swap (`quote`, `swap`, `prices`, `health` and the REST quote), WebSocket
|
|
5
|
+
subscriptions, Carbon Stream (Yellowstone gRPC, an optional extra), the account API, webhook signature checks, the DCA
|
|
6
|
+
API on the dex and the token API. Blocking and asyncio clients. Python 3.11 and newer. Types ship with the package.
|
|
7
|
+
|
|
8
|
+
The package never holds a private key, signs or sends on its own: swap and DCA calls return one unsigned transaction
|
|
9
|
+
for your own wallet to sign, and `send_transaction` takes a transaction you signed, as a string: base58, or base64
|
|
10
|
+
with `encoding` set to `base64`. Every method it offers is served; what the services do not serve is not here.
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
pip install carbium
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Carbon Stream needs the extra: `pip install 'carbium[stream]'`.
|
|
17
|
+
|
|
18
|
+
## Quick start
|
|
19
|
+
|
|
20
|
+
A service key (`c_serv_…`) comes from the dashboard at carbium.sh; put it in `CARBIUM_KEY`. Without one the call
|
|
21
|
+
reaches the door and is refused with 401, which the quick start prints.
|
|
22
|
+
|
|
23
|
+
```python
|
|
24
|
+
import os
|
|
25
|
+
|
|
26
|
+
from carbium import Carbium, CarbiumError
|
|
27
|
+
|
|
28
|
+
carbium = Carbium(os.environ.get("CARBIUM_KEY"))
|
|
29
|
+
try:
|
|
30
|
+
answer = carbium.get_latest_blockhash()
|
|
31
|
+
value = answer["value"]
|
|
32
|
+
print("blockhash", value["blockhash"], "valid until block height", value["lastValidBlockHeight"], "at slot", answer["context"]["slot"])
|
|
33
|
+
except CarbiumError as error:
|
|
34
|
+
print(error.kind, error.http_status, error.code, error.reason, error.message)
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## RPC, DAS and the quote
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
import os
|
|
41
|
+
|
|
42
|
+
from carbium import AsyncCarbium, Carbium
|
|
43
|
+
|
|
44
|
+
carbium = Carbium(os.environ["CARBIUM_KEY"])
|
|
45
|
+
|
|
46
|
+
# Standard Solana methods take positional params, as on the wire, in snake case.
|
|
47
|
+
balance = carbium.get_balance("So11111111111111111111111111111111111111112")
|
|
48
|
+
accounts = carbium.get_multiple_accounts([a, b], {"encoding": "base64"})
|
|
49
|
+
|
|
50
|
+
# DAS methods take their fields by name.
|
|
51
|
+
asset = carbium.get_asset(id=mint)
|
|
52
|
+
|
|
53
|
+
# Any served method by its wire name.
|
|
54
|
+
slot = carbium.rpc("getSlot", [{"commitment": "confirmed"}])
|
|
55
|
+
|
|
56
|
+
# A JSON-RPC batch: 1 to 100 calls, at most two permit methods, DAS only with DAS.
|
|
57
|
+
results = carbium.batch([("getSlot", []), ("getHealth", [])])
|
|
58
|
+
|
|
59
|
+
# A transaction your own wallet signed, sent as base64. It is never sent twice.
|
|
60
|
+
signature = carbium.send_transaction(signed_base64, {"encoding": "base64"})
|
|
61
|
+
|
|
62
|
+
# The REST quote, GET /cq1/quote: every value of the answer is a string.
|
|
63
|
+
quote = carbium.cq1_quote(SOL, USDC, 100_000_000, 50)
|
|
64
|
+
|
|
65
|
+
# The same calls on asyncio.
|
|
66
|
+
async def latest_slot() -> int:
|
|
67
|
+
async with AsyncCarbium(os.environ["CARBIUM_KEY"]) as client:
|
|
68
|
+
return await client.get_slot()
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Token scans (`getTokenAccountsByOwner`, `getTokenAccountsByDelegate`) are billed by rows, up to 100,005 credits;
|
|
72
|
+
`getProgramAccounts` costs 505; a `getTransactionsForAddress` walk costs 55 plus 50 per upstream call after the first,
|
|
73
|
+
up to 51,255 at `limit` 1000. Name a mint, keep `limit` small, and read the method notes at
|
|
74
|
+
https://carbium.sh/skill.md before running one in a loop.
|
|
75
|
+
|
|
76
|
+
## Errors and retries
|
|
77
|
+
|
|
78
|
+
Every failure is a `CarbiumError`.
|
|
79
|
+
|
|
80
|
+
| Field | Meaning |
|
|
81
|
+
|---|---|
|
|
82
|
+
| `kind` | `auth`, `credits`, `rate_limit`, `request`, `upstream`, `node`, `route`, `transport`, `socket`, `stream`, `account`, `dca`, `tokens`, `webhook` |
|
|
83
|
+
| `http_status` | the HTTP status, 0 when nothing answered |
|
|
84
|
+
| `code` | the JSON-RPC code, an HTTP API's error string, or a close code |
|
|
85
|
+
| `reason` | the door's `error.data.reason`, a close reason, or a gRPC status name |
|
|
86
|
+
| `retryable` | whether waiting and sending the same request can change the answer |
|
|
87
|
+
| `retry_after_ms` | the server's wait hint |
|
|
88
|
+
| `request_id` | `x-request-id`, to quote to support |
|
|
89
|
+
| `data` | `error.data` as served |
|
|
90
|
+
|
|
91
|
+
The RPC client follows the retry policy published in skill.md: it waits the larger of the server's hint
|
|
92
|
+
(`retry-after-ms`, else `retryAfterMs` in the error's data, else `Retry-After`) and 250 ms doubling to 4 s, plus up to
|
|
93
|
+
250 ms of jitter, and tries at most 4 times unless the published row says otherwise. A hint over `max_hint_ms` (30 s
|
|
94
|
+
by default) is not waited for: the error comes back at once with it in `retry_after_ms`. `send_transaction`, 401,
|
|
95
|
+
402 (credits exhausted), 403, bad params (apart from `get_transactions_for_address`'s `-32602` "the walk read no
|
|
96
|
+
history", which is retried), unknown methods and every answer marked `retryable: false` are never retried.
|
|
97
|
+
`Carbium(retry=False)` turns retries off; `max_attempts` lowers the attempt count. The account, DCA and token clients
|
|
98
|
+
never retry: they hand back `retryable` and `retry_after_ms`. Keys, session tokens and webhook secrets never appear
|
|
99
|
+
in error messages, data, reprs or logs.
|
|
100
|
+
|
|
101
|
+
## WebSocket subscriptions (asyncio)
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
import asyncio
|
|
105
|
+
import os
|
|
106
|
+
|
|
107
|
+
from carbium import CarbiumSocket
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
async def main() -> None:
|
|
111
|
+
async with CarbiumSocket(os.environ["CARBIUM_KEY"], on_reseed=lambda info: print("re-read state", info)) as socket:
|
|
112
|
+
sub = socket.account_subscribe(pubkey, lambda n: print(n["context"]["slot"], n["value"]["lamports"]), {"commitment": "confirmed"})
|
|
113
|
+
await sub.ready
|
|
114
|
+
...
|
|
115
|
+
await sub.unsubscribe()
|
|
116
|
+
|
|
117
|
+
asyncio.run(main())
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
All eight served subscriptions have a call (`account_subscribe`, `program_subscribe`, `logs_subscribe`,
|
|
121
|
+
`signature_subscribe`, `slot_subscribe`, `root_subscribe`, `slots_updates_subscribe`, `block_subscribe`). The key
|
|
122
|
+
travels in the `x-api-key` header, never in the address. The client follows the server's close codes: it reconnects
|
|
123
|
+
and binds every live subscription again after 1013, 1012, 1001 and network drops, reconnects once after 1008
|
|
124
|
+
`credits_exhausted`, and stops with `on_fatal` on a key refusal (close 1008 `key_…`, or a handshake refused with 401
|
|
125
|
+
or 403); a handshake refused with 429 waits its `Retry-After`. Nothing is replayed by the
|
|
126
|
+
server after a disconnect: `on_reseed` fires after every reconnect so you re-read what you may have missed
|
|
127
|
+
(`info["gap"]` is true after `stream_gap_reseed_required`). `signature_subscribe` fires once; after a reconnect, check
|
|
128
|
+
`getSignatureStatuses`.
|
|
129
|
+
|
|
130
|
+
## Carbon Stream (Yellowstone gRPC, asyncio)
|
|
131
|
+
|
|
132
|
+
Install the extra beside the package: `pip install 'carbium[stream]'` (grpcio and protobuf; nothing else needs them,
|
|
133
|
+
and `import carbium` never loads them). The key needs the grpc scope and a plan with streams.
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
import os
|
|
137
|
+
|
|
138
|
+
from carbium import CarbiumStream
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
async def main() -> None:
|
|
142
|
+
async with await CarbiumStream.connect(os.environ["CARBIUM_KEY"]) as stream:
|
|
143
|
+
live = stream.subscribe_with_reconnect(
|
|
144
|
+
{"transactions": {"pool": {"account_include": [program_id], "vote": False, "failed": False}}},
|
|
145
|
+
on_update=lambda u: handle(u.transaction) if u.HasField("transaction") else None,
|
|
146
|
+
on_reseed=lambda info: reload_over_rpc(),
|
|
147
|
+
)
|
|
148
|
+
...
|
|
149
|
+
live.close()
|
|
150
|
+
await live.done
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Filters use the proto field names (`accounts`, `slots`, `transactions`, `transactions_status`, `blocks`,
|
|
154
|
+
`blocks_meta`, `entry`, `commitment`, `accounts_data_slice`, `from_slot`), and updates are the Yellowstone
|
|
155
|
+
`SubscribeUpdate` messages. `subscribe_with_reconnect` puts the whole filter set in the first message (a filter change
|
|
156
|
+
needs a new stream), pings every 10 s, retries with the published waits, re-seeds through `on_reseed` on
|
|
157
|
+
`OUT_OF_RANGE`, and resumes from the last slot when the retained floor allows (a resume can replay a slot you already
|
|
158
|
+
saw: dedupe on `(slot, signature)`). It stops on a key, plan, argument or credits refusal and raises it from
|
|
159
|
+
`live.done`. Fields the service refuses (`token_accounts`, cuckoo filters, `include_update_parent`, `block_footer`)
|
|
160
|
+
and a bare transaction filter are caught before any call. The seven unary calls (`get_slot`, `get_block_height`,
|
|
161
|
+
`get_latest_blockhash`, `is_blockhash_valid`, `get_version`, `ping`, `subscribe_replay_info`) are on the same object.
|
|
162
|
+
`on_update` is called, never awaited, and must not block (a reader that takes no frame for 10 s is cut): a coroutine
|
|
163
|
+
function is refused, so hand slow work to your own task or queue. An exception from a handler stops the stream and is
|
|
164
|
+
raised from `live.done`. The key travels as `x-token` metadata; gRPC's
|
|
165
|
+
own `GRPC_TRACE` logging prints metadata, so leave it off while a key is in use. The generated messages come from the
|
|
166
|
+
upstream Yellowstone protos (Apache-2.0): see `carbium/_geyser/NOTICE`.
|
|
167
|
+
|
|
168
|
+
## Webhooks
|
|
169
|
+
|
|
170
|
+
```python
|
|
171
|
+
import os
|
|
172
|
+
|
|
173
|
+
from carbium import verify_webhook
|
|
174
|
+
|
|
175
|
+
# in your HTTPS handler, with the RAW body bytes (never a re-encoded JSON string)
|
|
176
|
+
events = verify_webhook(raw_body, request.headers, os.environ["CARBIUM_WEBHOOK_SECRET"])
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Standard Webhooks: HMAC-SHA256 over `webhook-id.webhook-timestamp.body` with the secret's base64 after `whsec_`,
|
|
180
|
+
`v1,` entries in `webhook-signature` (two during a rotation), 300 s of clock tolerance, header names in any case.
|
|
181
|
+
Raises a `CarbiumError` of kind `webhook` with reason `missing_header`, `bad_timestamp`, `stale`, `bad_secret`,
|
|
182
|
+
`no_match` or `bad_json`. Dedupe on `webhook-id`: it stays the same across retries.
|
|
183
|
+
|
|
184
|
+
## Account API
|
|
185
|
+
|
|
186
|
+
An account API key (`c_acct_…`, made on the dashboard) runs the account by API: service keys, webhooks, usage and
|
|
187
|
+
records. Put it in `CARBIUM_ACCOUNT_KEY`.
|
|
188
|
+
|
|
189
|
+
```python
|
|
190
|
+
import os
|
|
191
|
+
|
|
192
|
+
from carbium import CarbiumAccount
|
|
193
|
+
|
|
194
|
+
account = CarbiumAccount(os.environ["CARBIUM_ACCOUNT_KEY"])
|
|
195
|
+
keys = account.keys_list()
|
|
196
|
+
created = account.webhooks_create({"key_id": keys[0]["key_id"], "url": "https://hooks.example.com/carbium", "addresses": [wallet]})
|
|
197
|
+
result = account.webhooks_test(created["webhook"]["webhook_id"]) # read result["outcome"]
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Every operation of the account API has one call, generated from its description, 53 in all. The names are the
|
|
201
|
+
TypeScript SDK's in snake case: `keys_list`, `keys_create`, `keys_rotate`, `webhooks_test`, `usage_daily`,
|
|
202
|
+
`account_balance`, `self`, `activity`, and so on. Path ids are integers. A call that takes a session (made by a
|
|
203
|
+
sign-in) is refused before it is sent when the client holds only an account key: pass `session_token=` for those.
|
|
204
|
+
The public calls (`terms`, `plans`, `signup_challenge`, `pin_start`, `pin_verify`, `wallet_login`) send no
|
|
205
|
+
credential.
|
|
206
|
+
|
|
207
|
+
## DCA API
|
|
208
|
+
|
|
209
|
+
```python
|
|
210
|
+
from carbium import CarbiumDca
|
|
211
|
+
|
|
212
|
+
dca = CarbiumDca()
|
|
213
|
+
quote = dca.quote({"inputMint": USDC, "outputMint": SOL, "amount": "1000000"})
|
|
214
|
+
build = dca.open({"owner": owner, "inputMint": USDC, "outputMint": SOL, "cycles": 10, "amountPerCycle": "1000000", "frequency": "daily"})
|
|
215
|
+
# build["txn_base64"] is unsigned: sign it with the owner's wallet, then send it yourself or relay it:
|
|
216
|
+
sent = dca.send({"txn_base64": signed_base64})
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Reads: `quote`, `positions`, `history`, `position`, `health`. Builders: `open`, `update`, `withdraw`, `close`. `send`
|
|
220
|
+
relays bytes the owner signed, once. An answer with `ok: false` is an error even at HTTP 200, and the codes
|
|
221
|
+
`rate_limited`, `rate_limited_open`, `rpc_unavailable`, `quote_unavailable` and `door_busy` may be tried again at any
|
|
222
|
+
status. Errors are kind `dca` with the API's `err` string as `code`.
|
|
223
|
+
|
|
224
|
+
## Token API
|
|
225
|
+
|
|
226
|
+
```python
|
|
227
|
+
from carbium import CarbiumTokens
|
|
228
|
+
|
|
229
|
+
tokens = CarbiumTokens()
|
|
230
|
+
sol = tokens.lookup("So11111111111111111111111111111111111111112") # None when the registry does not hold it
|
|
231
|
+
top = tokens.search("", limit=20)
|
|
232
|
+
found = tokens.batch(mints) # 1 to 500 mints
|
|
233
|
+
src = tokens.image_url(mint)
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Keyless, 300 requests a minute per client. The four public routes: `search`, `lookup` (None until a mint is indexed),
|
|
237
|
+
`batch` (unknown mints are queued by the service) and `image_url` (always answers, with a fallback image).
|
|
238
|
+
|
|
239
|
+
## Limits checked before sending
|
|
240
|
+
|
|
241
|
+
Body 51,200 bytes; a batch holds 1 to 100 calls with at most two permit methods, DAS only with DAS; the scans,
|
|
242
|
+
`getSupply`, `getLargestAccounts`, the fee extras, `getTransactionsForAddress`, `prices`, `health`, `quote` and `swap`
|
|
243
|
+
never batch; a method the services do not serve is refused before it is sent; token `batch` takes up to 500 mints.
|
|
244
|
+
|
|
245
|
+
## Contributing
|
|
246
|
+
|
|
247
|
+
Enable the leak check once per clone: `git config core.hooksPath hooks`.
|
|
248
|
+
|
|
249
|
+
MIT. Docs: https://carbium.sh/docs and https://carbium.sh/skill.md.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["uv_build>=0.13.9,<0.14"]
|
|
3
|
+
build-backend = "uv_build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "carbium"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Typed Python client for Carbium's Solana services: RPC, DAS, quote and swap, WebSocket subscriptions, Carbon Stream, webhooks, the account API, DCA and the token API"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT AND Apache-2.0"
|
|
11
|
+
license-files = [
|
|
12
|
+
"LICENSE",
|
|
13
|
+
"src/carbium/_geyser/LICENSE",
|
|
14
|
+
"src/carbium/_geyser/NOTICE",
|
|
15
|
+
]
|
|
16
|
+
requires-python = ">=3.11"
|
|
17
|
+
dependencies = [
|
|
18
|
+
"httpx>=0.28.1,<0.29",
|
|
19
|
+
"websockets>=17.4,<18",
|
|
20
|
+
]
|
|
21
|
+
keywords = [
|
|
22
|
+
"solana",
|
|
23
|
+
"rpc",
|
|
24
|
+
"das",
|
|
25
|
+
"websocket",
|
|
26
|
+
"yellowstone",
|
|
27
|
+
"grpc",
|
|
28
|
+
"swap",
|
|
29
|
+
"dca",
|
|
30
|
+
"webhooks",
|
|
31
|
+
"carbium",
|
|
32
|
+
]
|
|
33
|
+
classifiers = [
|
|
34
|
+
"Development Status :: 4 - Beta",
|
|
35
|
+
"Framework :: AsyncIO",
|
|
36
|
+
"Intended Audience :: Developers",
|
|
37
|
+
"Operating System :: OS Independent",
|
|
38
|
+
"Programming Language :: Python :: 3",
|
|
39
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
40
|
+
"Programming Language :: Python :: 3.11",
|
|
41
|
+
"Programming Language :: Python :: 3.12",
|
|
42
|
+
"Programming Language :: Python :: 3.13",
|
|
43
|
+
"Programming Language :: Python :: 3.14",
|
|
44
|
+
"Programming Language :: Python :: 3.15",
|
|
45
|
+
"Topic :: Software Development :: Libraries",
|
|
46
|
+
"Typing :: Typed",
|
|
47
|
+
]
|
|
48
|
+
|
|
49
|
+
[project.optional-dependencies]
|
|
50
|
+
stream = [
|
|
51
|
+
"grpcio>=1.85.3,<2",
|
|
52
|
+
"protobuf>=7.35.1,<8",
|
|
53
|
+
]
|
|
54
|
+
|
|
55
|
+
[project.urls]
|
|
56
|
+
Homepage = "https://carbium.sh"
|
|
57
|
+
Documentation = "https://carbium.sh/docs"
|
|
58
|
+
Repository = "https://github.com/carbium-sh/carbium-py"
|
|
59
|
+
Issues = "https://github.com/carbium-sh/carbium-py/issues"
|
|
60
|
+
|
|
61
|
+
[dependency-groups]
|
|
62
|
+
dev = [
|
|
63
|
+
"pytest>=9.2",
|
|
64
|
+
"grpcio-tools==1.85.3",
|
|
65
|
+
]
|
|
66
|
+
|
|
67
|
+
[tool.pytest.ini_options]
|
|
68
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["uv_build>=0.13.9,<0.14"]
|
|
3
|
+
build-backend = "uv_build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "carbium"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "Typed Python client for Carbium's Solana services: RPC, DAS, quote and swap, WebSocket subscriptions, Carbon Stream, webhooks, the account API, DCA and the token API"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT AND Apache-2.0"
|
|
11
|
+
license-files = ["LICENSE", "src/carbium/_geyser/LICENSE", "src/carbium/_geyser/NOTICE"]
|
|
12
|
+
requires-python = ">=3.11"
|
|
13
|
+
dependencies = ["httpx>=0.28.1,<0.29", "websockets>=17.4,<18"]
|
|
14
|
+
|
|
15
|
+
keywords = ["solana", "rpc", "das", "websocket", "yellowstone", "grpc", "swap", "dca", "webhooks", "carbium"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 4 - Beta",
|
|
18
|
+
"Framework :: AsyncIO",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"Operating System :: OS Independent",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
23
|
+
"Programming Language :: Python :: 3.11",
|
|
24
|
+
"Programming Language :: Python :: 3.12",
|
|
25
|
+
"Programming Language :: Python :: 3.13",
|
|
26
|
+
"Programming Language :: Python :: 3.14",
|
|
27
|
+
"Programming Language :: Python :: 3.15",
|
|
28
|
+
"Topic :: Software Development :: Libraries",
|
|
29
|
+
"Typing :: Typed",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.optional-dependencies]
|
|
33
|
+
# Carbon Stream: the generated modules need grpcio 1.85.3 and protobuf 7.35.1 or newer within their majors.
|
|
34
|
+
stream = ["grpcio>=1.85.3,<2", "protobuf>=7.35.1,<8"]
|
|
35
|
+
|
|
36
|
+
[project.urls]
|
|
37
|
+
Homepage = "https://carbium.sh"
|
|
38
|
+
Documentation = "https://carbium.sh/docs"
|
|
39
|
+
Repository = "https://github.com/carbium-sh/carbium-py"
|
|
40
|
+
Issues = "https://github.com/carbium-sh/carbium-py/issues"
|
|
41
|
+
|
|
42
|
+
[dependency-groups]
|
|
43
|
+
dev = ["pytest>=9.2", "grpcio-tools==1.85.3"]
|
|
44
|
+
|
|
45
|
+
[tool.pytest.ini_options]
|
|
46
|
+
testpaths = ["tests"]
|