pax-api 2.2.0__tar.gz → 2.4.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.
pax_api-2.4.0/PKG-INFO ADDED
@@ -0,0 +1,277 @@
1
+ Metadata-Version: 2.4
2
+ Name: pax-api
3
+ Version: 2.4.0
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.4.0"
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.4.0"
30
30
 
31
31
  from pax_api.client import PaxClient # noqa: E402
32
32
  from pax_api.ws_client import PaxWSClient # noqa: E402
@@ -17,6 +17,8 @@ Environment:
17
17
  from __future__ import annotations
18
18
 
19
19
  import json as _json
20
+ import os
21
+ import secrets
20
22
  from typing import Any, Callable, Dict, List, Optional
21
23
 
22
24
  import requests
@@ -25,7 +27,7 @@ from pax_api.auth import sign_request
25
27
  from pax_api.errors import PaxError, build_error
26
28
  from pax_api.retry import run_with_retry
27
29
 
28
- __version__ = "2.2.0" # keep in sync with __init__.py + pyproject.toml
30
+ __version__ = "2.4.0" # keep in sync with __init__.py + pyproject.toml
29
31
 
30
32
 
31
33
  # v2: sandbox is a tier on the key, not a separate host. All env aliases
@@ -114,7 +116,8 @@ class PaxClient:
114
116
  return headers
115
117
 
116
118
  def _do_request(self, method: str, path: str, params: Optional[Dict[str, Any]] = None,
117
- json_body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
119
+ json_body: Optional[Dict[str, Any]] = None,
120
+ extra_headers: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
118
121
  url = self.base_url + path
119
122
  body = _json.dumps(json_body, separators=(",", ":"), sort_keys=False) if json_body is not None else ""
120
123
  # Reconstruct path+query for signing to match what server sees
@@ -126,6 +129,11 @@ class PaxClient:
126
129
  if qs:
127
130
  path_for_sig = f"{path}?{qs}"
128
131
  headers = self._headers_for(method, path_for_sig, body)
132
+ if extra_headers:
133
+ headers.update(extra_headers)
134
+ # Auto-inject Idempotency-Key for POST/PUT/PATCH/DELETE if not set by caller
135
+ if method.upper() in ("POST", "PUT", "PATCH", "DELETE") and "Idempotency-Key" not in headers:
136
+ headers["Idempotency-Key"] = "pax-sdk-" + secrets.token_hex(12)
129
137
 
130
138
  resp = self._session.request(
131
139
  method=method,
@@ -152,9 +160,11 @@ class PaxClient:
152
160
  return payload
153
161
 
154
162
  def _request(self, method: str, path: str, params: Optional[Dict[str, Any]] = None,
155
- json_body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
163
+ json_body: Optional[Dict[str, Any]] = None,
164
+ extra_headers: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
156
165
  return run_with_retry(
157
- lambda: self._do_request(method, path, params=params, json_body=json_body),
166
+ lambda: self._do_request(method, path, params=params, json_body=json_body,
167
+ extra_headers=extra_headers),
158
168
  max_attempts=self.max_retries,
159
169
  )
160
170
 
@@ -434,6 +444,41 @@ class PaxClient:
434
444
  """GET /v1/apply/{code} — check application review status."""
435
445
  return self._request("GET", f"/v1/apply/{application_code}")
436
446
 
447
+ # ── Revenue / settle (v2.4+) ─────────────────────────────────────────────
448
+ def settle_self(self, *, address: str, asset: str = "USDT",
449
+ network: str = "polygon", min_amount: float = 0) -> Dict[str, Any]:
450
+ """POST /v1/builders/me/settle — builder self-serve claim of accrued
451
+ execution_builder + acquisition_builder fees. Creates a withdrawal_state
452
+ row; existing pipeline delivers USDT to the provided address.
453
+ Requires api-key auth (uses the caller's user_id as builder identity).
454
+ """
455
+ return self._request("POST", "/v1/builders/me/settle",
456
+ json_body={"address": address, "asset": asset,
457
+ "network": network, "min_amount": min_amount})
458
+
459
+ def admin_settle_builder(self, user_id: str, *, address: str, asset: str = "USDT",
460
+ network: str = "polygon", min_amount: float = 0,
461
+ admin_key: Optional[str] = None) -> Dict[str, Any]:
462
+ """POST /v1/admin/builders/{user_id}/settle — admin claim of a specific
463
+ builder's earnings. Requires X-Admin-Key (pass via admin_key arg or
464
+ env ADMIN_HEALTH_TOKEN)."""
465
+ headers = {"X-Admin-Key": admin_key or os.environ.get("ADMIN_HEALTH_TOKEN", "")}
466
+ return self._request("POST", f"/v1/admin/builders/{user_id}/settle",
467
+ json_body={"address": address, "asset": asset,
468
+ "network": network, "min_amount": min_amount},
469
+ extra_headers=headers)
470
+
471
+ def admin_settle_creator(self, user_id: str, *, address: str, asset: str = "USDT",
472
+ network: str = "polygon", min_amount: float = 0,
473
+ admin_key: Optional[str] = None) -> Dict[str, Any]:
474
+ """POST /v1/admin/creators/{user_id}/settle — admin claim of a specific
475
+ market creator's FEE_MARKET_CREATOR earnings. Requires X-Admin-Key."""
476
+ headers = {"X-Admin-Key": admin_key or os.environ.get("ADMIN_HEALTH_TOKEN", "")}
477
+ return self._request("POST", f"/v1/admin/creators/{user_id}/settle",
478
+ json_body={"address": address, "asset": asset,
479
+ "network": network, "min_amount": min_amount},
480
+ extra_headers=headers)
481
+
437
482
  # ── Helpers ──────────────────────────────────────────────────────────────
438
483
  def close(self) -> None:
439
484
  self._session.close()