pax-api 2.2.0__tar.gz → 2.2.1__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.
pax_api-2.2.1/PKG-INFO ADDED
@@ -0,0 +1,277 @@
1
+ Metadata-Version: 2.4
2
+ Name: pax-api
3
+ Version: 2.2.1
4
+ Summary: Official Python SDK for the PredictAsiaX Trader Track API — Web3-native prediction markets
5
+ Author-email: PredictAsiaX <support@predictasiax.com>
6
+ License: MIT
7
+ Project-URL: Homepage, https://predictasiax.com/developer
8
+ Project-URL: Documentation, https://docs.predictasiax.com
9
+ Project-URL: Repository, https://github.com/predictasiax/pax-python-sdk
10
+ Project-URL: Issues, https://github.com/predictasiax/pax-python-sdk/issues
11
+ Project-URL: Changelog, https://docs.predictasiax.com/changelog
12
+ Keywords: predictasiax,pax,prediction-market,trading-api,web3,hmac,polymarket-compatible
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Financial and Insurance Industry
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.8
20
+ Classifier: Programming Language :: Python :: 3.9
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Classifier: Topic :: Office/Business :: Financial :: Investment
25
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
26
+ Requires-Python: >=3.8
27
+ Description-Content-Type: text/markdown
28
+ License-File: LICENSE
29
+ Requires-Dist: requests>=2.28
30
+ Requires-Dist: websocket-client>=1.5
31
+ Provides-Extra: dev
32
+ Requires-Dist: pytest>=7; extra == "dev"
33
+ Requires-Dist: pytest-cov>=4; extra == "dev"
34
+ Requires-Dist: responses>=0.23; extra == "dev"
35
+ Requires-Dist: ruff>=0.1; extra == "dev"
36
+ Requires-Dist: mypy>=1; extra == "dev"
37
+ Requires-Dist: build>=1; extra == "dev"
38
+ Requires-Dist: twine>=4; extra == "dev"
39
+ Dynamic: license-file
40
+
41
+ # pax-api — Official Python SDK for PredictAsiaX
42
+
43
+ Web3-native prediction market REST + WebSocket API client. Polymarket-compatible HMAC signing pattern.
44
+
45
+ **Version 2.2.1** · MIT license · Python 3.8+
46
+
47
+ - **Docs**: https://docs.predictasiax.com
48
+ - **Verify**: https://docs.predictasiax.com/verify — public Merkle verifier over the operational ledger
49
+ - **Get API key**: https://predictasiax.com/settings/api-keys
50
+ - **Sandbox key (anonymous, 30 seconds)**: `POST /v1/sandbox-keys`
51
+ - **Support**: support@predictasiax.com
52
+
53
+ ## Install
54
+
55
+ ```bash
56
+ pip install pax-api
57
+ ```
58
+
59
+ Upgrade:
60
+
61
+ ```bash
62
+ pip install --upgrade pax-api
63
+ ```
64
+
65
+ ## Quickstart — sandbox key in 30 seconds (no email)
66
+
67
+ ```python
68
+ from pax_api import PaxClient
69
+
70
+ # Mint an anonymous sandbox key
71
+ with PaxClient(env="sandbox") as pax:
72
+ res = pax.mint_sandbox_key(org_name="my-app")
73
+ key = res["data"]["api_key"]
74
+ tier = res["data"]["tier"] # e.g. "self_serve"
75
+ limits = res["data"]["limits"] # e.g. {"per_order_usdt": 10, "per_day_usdt": 100}
76
+
77
+ # Use the key
78
+ with PaxClient(api_key=key, env="sandbox") as pax:
79
+ markets = pax.list_markets(category="crypto", limit=10)
80
+ for m in markets["data"]["items"]:
81
+ print(m["market_id"], m["question"])
82
+ ```
83
+
84
+ Same production host either way (`api.predictasiax.com/v1`). Sandbox tier is enforced on the key — no prefix magic.
85
+
86
+ ## Production trading (HMAC-signed)
87
+
88
+ Machine-to-machine bots use HMAC signing (Polymarket-compatible 5-header pattern):
89
+
90
+ ```python
91
+ from pax_api import PaxClient
92
+
93
+ pax = PaxClient(
94
+ api_key="sk_live_YOUR_KEY",
95
+ secret="<64-hex secret>",
96
+ passphrase="<passphrase>",
97
+ env="production",
98
+ )
99
+
100
+ pax.place_order(
101
+ market_id="m_...",
102
+ outcome_id="yes",
103
+ side="buy",
104
+ order_type="limit",
105
+ size="100",
106
+ price="0.55",
107
+ client_order_id="unique-per-intent-id", # retry-safe within 24h
108
+ )
109
+ ```
110
+
111
+ ## Batch orders
112
+
113
+ Place or cancel up to 25 orders / 50 cancels per call:
114
+
115
+ ```python
116
+ res = pax.place_orders_batch([
117
+ {"market_id": "m_a", "outcome_id": "yes", "side": "buy", "order_type": "limit", "size": "10", "price": "0.55"},
118
+ {"market_id": "m_b", "outcome_id": "no", "side": "sell", "order_type": "limit", "size": "20", "price": "0.42"},
119
+ ])
120
+
121
+ for item in res["data"]["results"]:
122
+ print(item["ok"], item.get("order_id"), item.get("error"))
123
+
124
+ pax.cancel_orders_batch([o["order_id"] for o in res["data"]["results"] if o["ok"]])
125
+ ```
126
+
127
+ Env-driven caps: `BATCH_ORDERS_MAX` (default 25), `BATCH_CANCEL_MAX` (default 50).
128
+
129
+ ## Fee estimator
130
+
131
+ Preview the 5-actor fee split before you place a trade — same shape returned post-trade:
132
+
133
+ ```python
134
+ est = pax.estimate_fees(size="100", price="0.55")
135
+ print(est["data"]["fee_ledger"])
136
+ # {
137
+ # "acquisition_builder_bps": 10, "execution_builder_bps": 10,
138
+ # "operator_bps": 5, "market_creator_bps": 8, "lp_bps": 12,
139
+ # "platform_net_bps": 5, "total_bps": 50,
140
+ # "amounts": {"acquisition_builder": "0.055", ...},
141
+ # "ledger_preview": {...}
142
+ # }
143
+ ```
144
+
145
+ ## Public Merkle verifier
146
+
147
+ Every fill is recorded in a hash-chained `event_log`, batched into a Merkle tree, and anchored to a public URL (R2). You (or any third party) can independently verify inclusion — no auth required.
148
+
149
+ ```python
150
+ status = pax.audit_status()
151
+ print(status["data"])
152
+ # {"events": 110914, "batches": 7232, "anchored": 7231, ...}
153
+
154
+ # Get an inclusion proof for event seq=42
155
+ proof = pax.audit_proof(42)
156
+ leaf = proof["data"]["leaf"]
157
+ root = proof["data"]["root"]
158
+ path = proof["data"]["proof"]
159
+
160
+ # Verify client-side (no server round-trip needed)
161
+ assert PaxClient.verify_merkle_proof(leaf=leaf, root=root, proof=path)
162
+
163
+ # Optional: fetch the signed batch anchor
164
+ anchor = pax.audit_anchor(proof["data"]["batch_num"])
165
+ print(anchor["data"]["url"]) # publicly fetchable
166
+ ```
167
+
168
+ See https://docs.predictasiax.com/verify for the browser-side demo + 4-language snippets.
169
+
170
+ ## WebSocket streams
171
+
172
+ ```python
173
+ from pax_api import PaxWSClient
174
+
175
+ ws = PaxWSClient(
176
+ api_key=key,
177
+ env="sandbox",
178
+ subscribe_on_connect=["fast_tick", "trade_executed", "account"],
179
+ )
180
+ ws.on("fast_tick", lambda e: print("tick:", e))
181
+ ws.on("trade_executed", lambda e: print("trade:", e))
182
+ ws.on("account", lambda e: print("balance:", e.get("balance_free")))
183
+ ws.run_forever() # blocks; Ctrl+C to exit
184
+ ```
185
+
186
+ Auto-reconnect + exponential backoff built-in. Client methods supported: `subscribe`, `unsubscribe`, `auth`, `set_locale`.
187
+
188
+ ## Error handling
189
+
190
+ Every response error becomes a typed exception:
191
+
192
+ ```python
193
+ from pax_api import (
194
+ PaxClient,
195
+ PaxRateLimitError,
196
+ PaxReadOnlyModeError,
197
+ PaxValidationError,
198
+ PaxWrongEnvKeyError,
199
+ PaxError, # base class — catch-all
200
+ )
201
+
202
+ try:
203
+ pax.place_order(...)
204
+ except PaxRateLimitError as e:
205
+ time.sleep(e.retry_after or 5)
206
+ except PaxValidationError as e:
207
+ print(f"Bad request: {e.details}")
208
+ except PaxReadOnlyModeError:
209
+ print("Trading paused by ops")
210
+ except PaxWrongEnvKeyError:
211
+ print("Wrong environment key")
212
+ except PaxError as e:
213
+ print(f"[{e.code}] {e.message} (request_id={e.request_id})")
214
+ ```
215
+
216
+ ## Automatic retry
217
+
218
+ Built-in exponential backoff on `429`, `500`, `502`, `504`. `Retry-After` header respected on rate limits. Non-idempotent creates are safe when you send `client_order_id`.
219
+
220
+ ```python
221
+ pax = PaxClient(api_key=key, env="sandbox", max_retries=5)
222
+ # max_retries=0 disables retries entirely
223
+ ```
224
+
225
+ ## Environments
226
+
227
+ | Env | Base URL |
228
+ |--------------|--------------------------------------|
229
+ | `production` | `https://api.predictasiax.com/v1` |
230
+ | `sandbox` | `https://api.predictasiax.com/v1` |
231
+
232
+ Sandbox and production share the same host. Sandbox tier is enforced on the key (`tier=self_serve`), which caps per-order / per-day USDT — see the `POST /v1/sandbox-keys` response `limits` field.
233
+
234
+ ## Custom base URL
235
+
236
+ ```python
237
+ pax = PaxClient(api_key="...", base_url="https://your-mirror/api/v1")
238
+ ```
239
+
240
+ ## Applications (progressive trust)
241
+
242
+ Move from sandbox → trade-capped → trade-full by submitting an application:
243
+
244
+ ```python
245
+ res = pax.apply(track="trader", org="my-org", contact="team@my-org.io")
246
+ print(res["data"]["application_code"]) # save this
247
+
248
+ status = pax.get_application(res["data"]["application_code"])
249
+ print(status["data"]["status"]) # submitted → in_review → approved / declined
250
+ ```
251
+
252
+ ## Development
253
+
254
+ ```bash
255
+ git clone https://github.com/predictasiax/pax-python-sdk
256
+ cd pax-python-sdk
257
+ pip install -e ".[dev]"
258
+ pytest # run all tests
259
+ ruff check src tests # lint
260
+ mypy src # type-check
261
+ ```
262
+
263
+ ## Links
264
+
265
+ - [OpenAPI spec](https://docs.predictasiax.com/openapi)
266
+ - [AsyncAPI (WebSocket) spec](https://docs.predictasiax.com/asyncapi)
267
+ - [Auth guide](https://docs.predictasiax.com/auth)
268
+ - [Verify (public Merkle verifier)](https://docs.predictasiax.com/verify)
269
+ - [Error codes](https://docs.predictasiax.com/errors)
270
+ - [Rate limits](https://docs.predictasiax.com/rate-limits)
271
+ - [FAQ](https://docs.predictasiax.com/faq)
272
+ - [Changelog](https://docs.predictasiax.com/changelog)
273
+ - [API Terms](https://docs.predictasiax.com/api-terms)
274
+
275
+ ## License
276
+
277
+ MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,237 @@
1
+ # pax-api — Official Python SDK for PredictAsiaX
2
+
3
+ Web3-native prediction market REST + WebSocket API client. Polymarket-compatible HMAC signing pattern.
4
+
5
+ **Version 2.2.1** · MIT license · Python 3.8+
6
+
7
+ - **Docs**: https://docs.predictasiax.com
8
+ - **Verify**: https://docs.predictasiax.com/verify — public Merkle verifier over the operational ledger
9
+ - **Get API key**: https://predictasiax.com/settings/api-keys
10
+ - **Sandbox key (anonymous, 30 seconds)**: `POST /v1/sandbox-keys`
11
+ - **Support**: support@predictasiax.com
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ pip install pax-api
17
+ ```
18
+
19
+ Upgrade:
20
+
21
+ ```bash
22
+ pip install --upgrade pax-api
23
+ ```
24
+
25
+ ## Quickstart — sandbox key in 30 seconds (no email)
26
+
27
+ ```python
28
+ from pax_api import PaxClient
29
+
30
+ # Mint an anonymous sandbox key
31
+ with PaxClient(env="sandbox") as pax:
32
+ res = pax.mint_sandbox_key(org_name="my-app")
33
+ key = res["data"]["api_key"]
34
+ tier = res["data"]["tier"] # e.g. "self_serve"
35
+ limits = res["data"]["limits"] # e.g. {"per_order_usdt": 10, "per_day_usdt": 100}
36
+
37
+ # Use the key
38
+ with PaxClient(api_key=key, env="sandbox") as pax:
39
+ markets = pax.list_markets(category="crypto", limit=10)
40
+ for m in markets["data"]["items"]:
41
+ print(m["market_id"], m["question"])
42
+ ```
43
+
44
+ Same production host either way (`api.predictasiax.com/v1`). Sandbox tier is enforced on the key — no prefix magic.
45
+
46
+ ## Production trading (HMAC-signed)
47
+
48
+ Machine-to-machine bots use HMAC signing (Polymarket-compatible 5-header pattern):
49
+
50
+ ```python
51
+ from pax_api import PaxClient
52
+
53
+ pax = PaxClient(
54
+ api_key="sk_live_YOUR_KEY",
55
+ secret="<64-hex secret>",
56
+ passphrase="<passphrase>",
57
+ env="production",
58
+ )
59
+
60
+ pax.place_order(
61
+ market_id="m_...",
62
+ outcome_id="yes",
63
+ side="buy",
64
+ order_type="limit",
65
+ size="100",
66
+ price="0.55",
67
+ client_order_id="unique-per-intent-id", # retry-safe within 24h
68
+ )
69
+ ```
70
+
71
+ ## Batch orders
72
+
73
+ Place or cancel up to 25 orders / 50 cancels per call:
74
+
75
+ ```python
76
+ res = pax.place_orders_batch([
77
+ {"market_id": "m_a", "outcome_id": "yes", "side": "buy", "order_type": "limit", "size": "10", "price": "0.55"},
78
+ {"market_id": "m_b", "outcome_id": "no", "side": "sell", "order_type": "limit", "size": "20", "price": "0.42"},
79
+ ])
80
+
81
+ for item in res["data"]["results"]:
82
+ print(item["ok"], item.get("order_id"), item.get("error"))
83
+
84
+ pax.cancel_orders_batch([o["order_id"] for o in res["data"]["results"] if o["ok"]])
85
+ ```
86
+
87
+ Env-driven caps: `BATCH_ORDERS_MAX` (default 25), `BATCH_CANCEL_MAX` (default 50).
88
+
89
+ ## Fee estimator
90
+
91
+ Preview the 5-actor fee split before you place a trade — same shape returned post-trade:
92
+
93
+ ```python
94
+ est = pax.estimate_fees(size="100", price="0.55")
95
+ print(est["data"]["fee_ledger"])
96
+ # {
97
+ # "acquisition_builder_bps": 10, "execution_builder_bps": 10,
98
+ # "operator_bps": 5, "market_creator_bps": 8, "lp_bps": 12,
99
+ # "platform_net_bps": 5, "total_bps": 50,
100
+ # "amounts": {"acquisition_builder": "0.055", ...},
101
+ # "ledger_preview": {...}
102
+ # }
103
+ ```
104
+
105
+ ## Public Merkle verifier
106
+
107
+ Every fill is recorded in a hash-chained `event_log`, batched into a Merkle tree, and anchored to a public URL (R2). You (or any third party) can independently verify inclusion — no auth required.
108
+
109
+ ```python
110
+ status = pax.audit_status()
111
+ print(status["data"])
112
+ # {"events": 110914, "batches": 7232, "anchored": 7231, ...}
113
+
114
+ # Get an inclusion proof for event seq=42
115
+ proof = pax.audit_proof(42)
116
+ leaf = proof["data"]["leaf"]
117
+ root = proof["data"]["root"]
118
+ path = proof["data"]["proof"]
119
+
120
+ # Verify client-side (no server round-trip needed)
121
+ assert PaxClient.verify_merkle_proof(leaf=leaf, root=root, proof=path)
122
+
123
+ # Optional: fetch the signed batch anchor
124
+ anchor = pax.audit_anchor(proof["data"]["batch_num"])
125
+ print(anchor["data"]["url"]) # publicly fetchable
126
+ ```
127
+
128
+ See https://docs.predictasiax.com/verify for the browser-side demo + 4-language snippets.
129
+
130
+ ## WebSocket streams
131
+
132
+ ```python
133
+ from pax_api import PaxWSClient
134
+
135
+ ws = PaxWSClient(
136
+ api_key=key,
137
+ env="sandbox",
138
+ subscribe_on_connect=["fast_tick", "trade_executed", "account"],
139
+ )
140
+ ws.on("fast_tick", lambda e: print("tick:", e))
141
+ ws.on("trade_executed", lambda e: print("trade:", e))
142
+ ws.on("account", lambda e: print("balance:", e.get("balance_free")))
143
+ ws.run_forever() # blocks; Ctrl+C to exit
144
+ ```
145
+
146
+ Auto-reconnect + exponential backoff built-in. Client methods supported: `subscribe`, `unsubscribe`, `auth`, `set_locale`.
147
+
148
+ ## Error handling
149
+
150
+ Every response error becomes a typed exception:
151
+
152
+ ```python
153
+ from pax_api import (
154
+ PaxClient,
155
+ PaxRateLimitError,
156
+ PaxReadOnlyModeError,
157
+ PaxValidationError,
158
+ PaxWrongEnvKeyError,
159
+ PaxError, # base class — catch-all
160
+ )
161
+
162
+ try:
163
+ pax.place_order(...)
164
+ except PaxRateLimitError as e:
165
+ time.sleep(e.retry_after or 5)
166
+ except PaxValidationError as e:
167
+ print(f"Bad request: {e.details}")
168
+ except PaxReadOnlyModeError:
169
+ print("Trading paused by ops")
170
+ except PaxWrongEnvKeyError:
171
+ print("Wrong environment key")
172
+ except PaxError as e:
173
+ print(f"[{e.code}] {e.message} (request_id={e.request_id})")
174
+ ```
175
+
176
+ ## Automatic retry
177
+
178
+ Built-in exponential backoff on `429`, `500`, `502`, `504`. `Retry-After` header respected on rate limits. Non-idempotent creates are safe when you send `client_order_id`.
179
+
180
+ ```python
181
+ pax = PaxClient(api_key=key, env="sandbox", max_retries=5)
182
+ # max_retries=0 disables retries entirely
183
+ ```
184
+
185
+ ## Environments
186
+
187
+ | Env | Base URL |
188
+ |--------------|--------------------------------------|
189
+ | `production` | `https://api.predictasiax.com/v1` |
190
+ | `sandbox` | `https://api.predictasiax.com/v1` |
191
+
192
+ Sandbox and production share the same host. Sandbox tier is enforced on the key (`tier=self_serve`), which caps per-order / per-day USDT — see the `POST /v1/sandbox-keys` response `limits` field.
193
+
194
+ ## Custom base URL
195
+
196
+ ```python
197
+ pax = PaxClient(api_key="...", base_url="https://your-mirror/api/v1")
198
+ ```
199
+
200
+ ## Applications (progressive trust)
201
+
202
+ Move from sandbox → trade-capped → trade-full by submitting an application:
203
+
204
+ ```python
205
+ res = pax.apply(track="trader", org="my-org", contact="team@my-org.io")
206
+ print(res["data"]["application_code"]) # save this
207
+
208
+ status = pax.get_application(res["data"]["application_code"])
209
+ print(status["data"]["status"]) # submitted → in_review → approved / declined
210
+ ```
211
+
212
+ ## Development
213
+
214
+ ```bash
215
+ git clone https://github.com/predictasiax/pax-python-sdk
216
+ cd pax-python-sdk
217
+ pip install -e ".[dev]"
218
+ pytest # run all tests
219
+ ruff check src tests # lint
220
+ mypy src # type-check
221
+ ```
222
+
223
+ ## Links
224
+
225
+ - [OpenAPI spec](https://docs.predictasiax.com/openapi)
226
+ - [AsyncAPI (WebSocket) spec](https://docs.predictasiax.com/asyncapi)
227
+ - [Auth guide](https://docs.predictasiax.com/auth)
228
+ - [Verify (public Merkle verifier)](https://docs.predictasiax.com/verify)
229
+ - [Error codes](https://docs.predictasiax.com/errors)
230
+ - [Rate limits](https://docs.predictasiax.com/rate-limits)
231
+ - [FAQ](https://docs.predictasiax.com/faq)
232
+ - [Changelog](https://docs.predictasiax.com/changelog)
233
+ - [API Terms](https://docs.predictasiax.com/api-terms)
234
+
235
+ ## License
236
+
237
+ MIT — see [LICENSE](LICENSE).
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "pax-api"
7
- version = "2.2.0"
7
+ version = "2.2.1"
8
8
  description = "Official Python SDK for the PredictAsiaX Trader Track API — Web3-native prediction markets"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.8"
@@ -26,7 +26,7 @@ caps), not a separate host. Same prefix, same URL — promote to production by
26
26
  upgrading the key's tier.
27
27
  """
28
28
 
29
- __version__ = "2.2.0"
29
+ __version__ = "2.2.1"
30
30
 
31
31
  from pax_api.client import PaxClient # noqa: E402
32
32
  from pax_api.ws_client import PaxWSClient # noqa: E402
@@ -25,7 +25,7 @@ from pax_api.auth import sign_request
25
25
  from pax_api.errors import PaxError, build_error
26
26
  from pax_api.retry import run_with_retry
27
27
 
28
- __version__ = "2.2.0" # keep in sync with __init__.py + pyproject.toml
28
+ __version__ = "2.2.1" # keep in sync with __init__.py + pyproject.toml
29
29
 
30
30
 
31
31
  # v2: sandbox is a tier on the key, not a separate host. All env aliases