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 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.
@@ -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"]