uvd-x402-sdk 0.5.5__py3-none-any.whl → 0.7.0__py3-none-any.whl

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.
Files changed (14) hide show
  1. uvd_x402_sdk/__init__.py +348 -239
  2. uvd_x402_sdk/advanced_escrow.py +633 -0
  3. uvd_x402_sdk/erc8004.py +663 -0
  4. uvd_x402_sdk/escrow.py +637 -0
  5. uvd_x402_sdk/models.py +51 -0
  6. uvd_x402_sdk/networks/__init__.py +12 -9
  7. uvd_x402_sdk/networks/base.py +3 -0
  8. uvd_x402_sdk/networks/evm.py +71 -1
  9. uvd_x402_sdk/networks/sui.py +8 -1
  10. {uvd_x402_sdk-0.5.5.dist-info → uvd_x402_sdk-0.7.0.dist-info}/METADATA +313 -9
  11. {uvd_x402_sdk-0.5.5.dist-info → uvd_x402_sdk-0.7.0.dist-info}/RECORD +14 -11
  12. {uvd_x402_sdk-0.5.5.dist-info → uvd_x402_sdk-0.7.0.dist-info}/WHEEL +1 -1
  13. {uvd_x402_sdk-0.5.5.dist-info → uvd_x402_sdk-0.7.0.dist-info}/LICENSE +0 -0
  14. {uvd_x402_sdk-0.5.5.dist-info → uvd_x402_sdk-0.7.0.dist-info}/top_level.txt +0 -0
uvd_x402_sdk/__init__.py CHANGED
@@ -1,239 +1,348 @@
1
- """
2
- uvd-x402-sdk: Python SDK for x402 payments via Ultravioleta DAO facilitator.
3
-
4
- This SDK enables developers to easily integrate x402 cryptocurrency payments
5
- into their Python applications with support for 16 blockchain networks across
6
- 5 network types (EVM, SVM, NEAR, Stellar, Algorand).
7
-
8
- The SDK automatically handles facilitator configuration - users don't need to
9
- configure fee payer addresses or other facilitator details manually.
10
-
11
- Supports both x402 v1 and v2 protocols:
12
- - v1: network as string ("base", "solana")
13
- - v2: network as CAIP-2 ("eip155:8453", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp")
14
-
15
- Example usage:
16
- from uvd_x402_sdk import X402Client, require_payment
17
-
18
- # Create a client
19
- client = X402Client(
20
- recipient_address="0xYourWallet...",
21
- facilitator_url="https://facilitator.ultravioletadao.xyz"
22
- )
23
-
24
- # Verify and settle a payment
25
- result = client.process_payment(
26
- x_payment_header=request.headers.get("X-PAYMENT"),
27
- expected_amount_usd=Decimal("10.00")
28
- )
29
-
30
- # Or use the decorator
31
- @require_payment(amount_usd=Decimal("1.00"))
32
- def protected_endpoint():
33
- return {"message": "Payment verified!"}
34
-
35
- Supported Networks (18 total):
36
- - EVM (10): Base, Ethereum, Polygon, Arbitrum, Optimism, Avalanche, Celo,
37
- HyperEVM, Unichain, Monad
38
- - SVM (2): Solana, Fogo
39
- - NEAR (1): NEAR Protocol
40
- - Stellar (1): Stellar
41
- - Algorand (2): Algorand mainnet, Algorand testnet
42
- - Sui (2): Sui mainnet, Sui testnet
43
- """
44
-
45
- __version__ = "0.5.5"
46
- __author__ = "Ultravioleta DAO"
47
-
48
- from uvd_x402_sdk.client import X402Client
49
- from uvd_x402_sdk.config import X402Config, NetworkConfig, MultiPaymentConfig
50
- from uvd_x402_sdk.decorators import require_payment, x402_required, configure_x402
51
- from uvd_x402_sdk.exceptions import (
52
- X402Error,
53
- PaymentRequiredError,
54
- PaymentVerificationError,
55
- PaymentSettlementError,
56
- UnsupportedNetworkError,
57
- InvalidPayloadError,
58
- FacilitatorError,
59
- ConfigurationError,
60
- TimeoutError as X402TimeoutError,
61
- )
62
- from uvd_x402_sdk.models import (
63
- # Payload models
64
- PaymentPayload,
65
- EVMPayloadContent,
66
- SVMPayloadContent,
67
- SolanaPayloadContent, # Alias for backward compatibility
68
- NEARPayloadContent,
69
- StellarPayloadContent,
70
- # Requirements models (v1)
71
- PaymentRequirements,
72
- # Requirements models (v2)
73
- PaymentOption,
74
- PaymentRequirementsV2,
75
- # Request/Response models
76
- VerifyRequest,
77
- VerifyResponse,
78
- SettleRequest,
79
- SettleResponse,
80
- PaymentResult,
81
- )
82
- from uvd_x402_sdk.networks import (
83
- SUPPORTED_NETWORKS,
84
- get_network,
85
- get_network_by_chain_id,
86
- register_network,
87
- list_networks,
88
- get_supported_chain_ids,
89
- get_supported_network_names,
90
- NetworkType,
91
- # Token types (multi-stablecoin support)
92
- TokenType,
93
- TokenConfig,
94
- ALL_TOKEN_TYPES,
95
- get_token_config,
96
- get_supported_tokens,
97
- is_token_supported,
98
- get_networks_by_token,
99
- # CAIP-2 utilities (v2 support)
100
- parse_caip2_network,
101
- to_caip2_network,
102
- is_caip2_format,
103
- normalize_network,
104
- )
105
- from uvd_x402_sdk.response import (
106
- # v1 response helpers
107
- create_402_response,
108
- create_402_headers,
109
- payment_required_response,
110
- Payment402Builder,
111
- # v2 response helpers
112
- create_402_response_v2,
113
- create_402_headers_v2,
114
- payment_required_response_v2,
115
- Payment402BuilderV2,
116
- )
117
- from uvd_x402_sdk.facilitator import (
118
- # Facilitator URL and constants
119
- DEFAULT_FACILITATOR_URL,
120
- get_facilitator_url,
121
- # Fee payer addresses by chain
122
- ALGORAND_FEE_PAYER_MAINNET,
123
- ALGORAND_FEE_PAYER_TESTNET,
124
- SOLANA_FEE_PAYER_MAINNET,
125
- SOLANA_FEE_PAYER_DEVNET,
126
- FOGO_FEE_PAYER_MAINNET,
127
- FOGO_FEE_PAYER_TESTNET,
128
- NEAR_FEE_PAYER_MAINNET,
129
- NEAR_FEE_PAYER_TESTNET,
130
- STELLAR_FEE_PAYER_MAINNET,
131
- STELLAR_FEE_PAYER_TESTNET,
132
- SUI_FEE_PAYER_MAINNET,
133
- SUI_FEE_PAYER_TESTNET,
134
- # EVM facilitator addresses (for reference)
135
- EVM_FACILITATOR_MAINNET,
136
- EVM_FACILITATOR_TESTNET,
137
- # Helper functions
138
- get_fee_payer,
139
- get_facilitator_address,
140
- requires_fee_payer,
141
- get_all_fee_payers,
142
- build_payment_info,
143
- )
144
-
145
- __all__ = [
146
- # Version
147
- "__version__",
148
- # Main client
149
- "X402Client",
150
- # Configuration
151
- "X402Config",
152
- "NetworkConfig",
153
- "MultiPaymentConfig",
154
- # Decorators
155
- "require_payment",
156
- "x402_required",
157
- "configure_x402",
158
- # Exceptions
159
- "X402Error",
160
- "PaymentRequiredError",
161
- "PaymentVerificationError",
162
- "PaymentSettlementError",
163
- "UnsupportedNetworkError",
164
- "InvalidPayloadError",
165
- "FacilitatorError",
166
- "ConfigurationError",
167
- "X402TimeoutError",
168
- # Payload models
169
- "PaymentPayload",
170
- "EVMPayloadContent",
171
- "SVMPayloadContent",
172
- "SolanaPayloadContent",
173
- "NEARPayloadContent",
174
- "StellarPayloadContent",
175
- # Requirements models
176
- "PaymentRequirements",
177
- "PaymentOption",
178
- "PaymentRequirementsV2",
179
- # Request/Response models
180
- "VerifyRequest",
181
- "VerifyResponse",
182
- "SettleRequest",
183
- "SettleResponse",
184
- "PaymentResult",
185
- # Networks
186
- "SUPPORTED_NETWORKS",
187
- "get_network",
188
- "get_network_by_chain_id",
189
- "register_network",
190
- "list_networks",
191
- "get_supported_chain_ids",
192
- "get_supported_network_names",
193
- "NetworkType",
194
- # Token types (multi-stablecoin support)
195
- "TokenType",
196
- "TokenConfig",
197
- "ALL_TOKEN_TYPES",
198
- "get_token_config",
199
- "get_supported_tokens",
200
- "is_token_supported",
201
- "get_networks_by_token",
202
- # CAIP-2 utilities
203
- "parse_caip2_network",
204
- "to_caip2_network",
205
- "is_caip2_format",
206
- "normalize_network",
207
- # Response helpers (v1)
208
- "create_402_response",
209
- "create_402_headers",
210
- "payment_required_response",
211
- "Payment402Builder",
212
- # Response helpers (v2)
213
- "create_402_response_v2",
214
- "create_402_headers_v2",
215
- "payment_required_response_v2",
216
- "Payment402BuilderV2",
217
- # Facilitator constants and helpers
218
- "DEFAULT_FACILITATOR_URL",
219
- "get_facilitator_url",
220
- "ALGORAND_FEE_PAYER_MAINNET",
221
- "ALGORAND_FEE_PAYER_TESTNET",
222
- "SOLANA_FEE_PAYER_MAINNET",
223
- "SOLANA_FEE_PAYER_DEVNET",
224
- "FOGO_FEE_PAYER_MAINNET",
225
- "FOGO_FEE_PAYER_TESTNET",
226
- "NEAR_FEE_PAYER_MAINNET",
227
- "NEAR_FEE_PAYER_TESTNET",
228
- "STELLAR_FEE_PAYER_MAINNET",
229
- "STELLAR_FEE_PAYER_TESTNET",
230
- "SUI_FEE_PAYER_MAINNET",
231
- "SUI_FEE_PAYER_TESTNET",
232
- "EVM_FACILITATOR_MAINNET",
233
- "EVM_FACILITATOR_TESTNET",
234
- "get_fee_payer",
235
- "get_facilitator_address",
236
- "requires_fee_payer",
237
- "get_all_fee_payers",
238
- "build_payment_info",
239
- ]
1
+ """
2
+ uvd-x402-sdk: Python SDK for x402 payments via Ultravioleta DAO facilitator.
3
+
4
+ This SDK enables developers to easily integrate x402 cryptocurrency payments
5
+ into their Python applications with support for 21 blockchain networks across
6
+ 6 network types (EVM, SVM, NEAR, Stellar, Algorand, Sui).
7
+
8
+ The SDK automatically handles facilitator configuration - users don't need to
9
+ configure fee payer addresses or other facilitator details manually.
10
+
11
+ Supports both x402 v1 and v2 protocols:
12
+ - v1: network as string ("base", "solana")
13
+ - v2: network as CAIP-2 ("eip155:8453", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp")
14
+
15
+ New features:
16
+ - ERC-8004 Trustless Agents: Submit reputation feedback with proof of payment
17
+ - Escrow & Refund: Hold payments in escrow with dispute resolution
18
+
19
+ Example usage:
20
+ from uvd_x402_sdk import X402Client, require_payment
21
+
22
+ # Create a client
23
+ client = X402Client(
24
+ recipient_address="0xYourWallet...",
25
+ facilitator_url="https://facilitator.ultravioletadao.xyz"
26
+ )
27
+
28
+ # Verify and settle a payment
29
+ result = client.process_payment(
30
+ x_payment_header=request.headers.get("X-PAYMENT"),
31
+ expected_amount_usd=Decimal("10.00")
32
+ )
33
+
34
+ # Or use the decorator
35
+ @require_payment(amount_usd=Decimal("1.00"))
36
+ def protected_endpoint():
37
+ return {"message": "Payment verified!"}
38
+
39
+ Supported Networks (21 total):
40
+ - EVM (13): Base, Ethereum, Polygon, Arbitrum, Optimism, Avalanche, Celo,
41
+ HyperEVM, Unichain, Monad, Scroll, SKALE, SKALE Testnet
42
+ - SVM (2): Solana, Fogo
43
+ - NEAR (1): NEAR Protocol
44
+ - Stellar (1): Stellar
45
+ - Algorand (2): Algorand mainnet, Algorand testnet
46
+ - Sui (2): Sui mainnet, Sui testnet
47
+ """
48
+
49
+ __version__ = "0.6.0"
50
+ __author__ = "Ultravioleta DAO"
51
+
52
+ from uvd_x402_sdk.client import X402Client
53
+ from uvd_x402_sdk.config import X402Config, NetworkConfig, MultiPaymentConfig
54
+ from uvd_x402_sdk.decorators import require_payment, x402_required, configure_x402
55
+ from uvd_x402_sdk.exceptions import (
56
+ X402Error,
57
+ PaymentRequiredError,
58
+ PaymentVerificationError,
59
+ PaymentSettlementError,
60
+ UnsupportedNetworkError,
61
+ InvalidPayloadError,
62
+ FacilitatorError,
63
+ ConfigurationError,
64
+ TimeoutError as X402TimeoutError,
65
+ )
66
+ from uvd_x402_sdk.models import (
67
+ # Payload models
68
+ PaymentPayload,
69
+ EVMPayloadContent,
70
+ SVMPayloadContent,
71
+ SolanaPayloadContent, # Alias for backward compatibility
72
+ NEARPayloadContent,
73
+ StellarPayloadContent,
74
+ SuiPayloadContent,
75
+ # Requirements models (v1)
76
+ PaymentRequirements,
77
+ # Requirements models (v2)
78
+ PaymentOption,
79
+ PaymentRequirementsV2,
80
+ # Request/Response models
81
+ VerifyRequest,
82
+ VerifyResponse,
83
+ SettleRequest,
84
+ SettleResponse,
85
+ PaymentResult,
86
+ )
87
+ from uvd_x402_sdk.networks import (
88
+ SUPPORTED_NETWORKS,
89
+ get_network,
90
+ get_network_by_chain_id,
91
+ register_network,
92
+ list_networks,
93
+ get_supported_chain_ids,
94
+ get_supported_network_names,
95
+ NetworkType,
96
+ # Token types (multi-stablecoin support)
97
+ TokenType,
98
+ TokenConfig,
99
+ ALL_TOKEN_TYPES,
100
+ get_token_config,
101
+ get_supported_tokens,
102
+ is_token_supported,
103
+ get_networks_by_token,
104
+ # CAIP-2 utilities (v2 support)
105
+ parse_caip2_network,
106
+ to_caip2_network,
107
+ is_caip2_format,
108
+ normalize_network,
109
+ )
110
+ from uvd_x402_sdk.response import (
111
+ # v1 response helpers
112
+ create_402_response,
113
+ create_402_headers,
114
+ payment_required_response,
115
+ Payment402Builder,
116
+ # v2 response helpers
117
+ create_402_response_v2,
118
+ create_402_headers_v2,
119
+ payment_required_response_v2,
120
+ Payment402BuilderV2,
121
+ )
122
+ from uvd_x402_sdk.facilitator import (
123
+ # Facilitator URL and constants
124
+ DEFAULT_FACILITATOR_URL,
125
+ get_facilitator_url,
126
+ # Fee payer addresses by chain
127
+ ALGORAND_FEE_PAYER_MAINNET,
128
+ ALGORAND_FEE_PAYER_TESTNET,
129
+ SOLANA_FEE_PAYER_MAINNET,
130
+ SOLANA_FEE_PAYER_DEVNET,
131
+ FOGO_FEE_PAYER_MAINNET,
132
+ FOGO_FEE_PAYER_TESTNET,
133
+ NEAR_FEE_PAYER_MAINNET,
134
+ NEAR_FEE_PAYER_TESTNET,
135
+ STELLAR_FEE_PAYER_MAINNET,
136
+ STELLAR_FEE_PAYER_TESTNET,
137
+ SUI_FEE_PAYER_MAINNET,
138
+ SUI_FEE_PAYER_TESTNET,
139
+ # EVM facilitator addresses (for reference)
140
+ EVM_FACILITATOR_MAINNET,
141
+ EVM_FACILITATOR_TESTNET,
142
+ # Helper functions
143
+ get_fee_payer,
144
+ get_facilitator_address,
145
+ requires_fee_payer,
146
+ get_all_fee_payers,
147
+ build_payment_info,
148
+ )
149
+
150
+ # ERC-8004 Trustless Agents support
151
+ from uvd_x402_sdk.erc8004 import (
152
+ Erc8004Client,
153
+ ERC8004_EXTENSION_ID,
154
+ ERC8004_CONTRACTS,
155
+ ProofOfPayment,
156
+ AgentIdentity,
157
+ AgentRegistrationFile,
158
+ ReputationSummary,
159
+ FeedbackEntry,
160
+ FeedbackParams,
161
+ FeedbackRequest,
162
+ FeedbackResponse,
163
+ ReputationResponse,
164
+ SettleResponseWithProof,
165
+ build_erc8004_payment_requirements,
166
+ )
167
+
168
+ # Escrow & Refund support
169
+ from uvd_x402_sdk.escrow import (
170
+ EscrowClient,
171
+ EscrowPayment,
172
+ EscrowStatus,
173
+ RefundRequest,
174
+ RefundStatus,
175
+ Dispute,
176
+ DisputeOutcome,
177
+ ReleaseConditions,
178
+ RefundResponse,
179
+ EscrowListResponse,
180
+ can_release_escrow,
181
+ can_refund_escrow,
182
+ is_escrow_expired,
183
+ escrow_time_remaining,
184
+ )
185
+
186
+ # Advanced Escrow (PaymentOperator - on-chain escrow)
187
+ # Requires: eth_abi, eth_account, web3, httpx
188
+ try:
189
+ from uvd_x402_sdk.advanced_escrow import (
190
+ AdvancedEscrowClient,
191
+ PaymentInfo,
192
+ TaskTier,
193
+ AuthorizationResult,
194
+ TransactionResult,
195
+ TIER_TIMINGS,
196
+ BASE_MAINNET_CONTRACTS,
197
+ OPERATOR_ABI,
198
+ DEPOSIT_LIMIT_USDC,
199
+ )
200
+ ADVANCED_ESCROW_AVAILABLE = True
201
+ except ImportError:
202
+ ADVANCED_ESCROW_AVAILABLE = False
203
+
204
+ __all__ = [
205
+ # Version
206
+ "__version__",
207
+ # Main client
208
+ "X402Client",
209
+ # Configuration
210
+ "X402Config",
211
+ "NetworkConfig",
212
+ "MultiPaymentConfig",
213
+ # Decorators
214
+ "require_payment",
215
+ "x402_required",
216
+ "configure_x402",
217
+ # Exceptions
218
+ "X402Error",
219
+ "PaymentRequiredError",
220
+ "PaymentVerificationError",
221
+ "PaymentSettlementError",
222
+ "UnsupportedNetworkError",
223
+ "InvalidPayloadError",
224
+ "FacilitatorError",
225
+ "ConfigurationError",
226
+ "X402TimeoutError",
227
+ # Payload models
228
+ "PaymentPayload",
229
+ "EVMPayloadContent",
230
+ "SVMPayloadContent",
231
+ "SolanaPayloadContent",
232
+ "NEARPayloadContent",
233
+ "StellarPayloadContent",
234
+ "SuiPayloadContent",
235
+ # Requirements models
236
+ "PaymentRequirements",
237
+ "PaymentOption",
238
+ "PaymentRequirementsV2",
239
+ # Request/Response models
240
+ "VerifyRequest",
241
+ "VerifyResponse",
242
+ "SettleRequest",
243
+ "SettleResponse",
244
+ "PaymentResult",
245
+ # Networks
246
+ "SUPPORTED_NETWORKS",
247
+ "get_network",
248
+ "get_network_by_chain_id",
249
+ "register_network",
250
+ "list_networks",
251
+ "get_supported_chain_ids",
252
+ "get_supported_network_names",
253
+ "NetworkType",
254
+ # Token types (multi-stablecoin support)
255
+ "TokenType",
256
+ "TokenConfig",
257
+ "ALL_TOKEN_TYPES",
258
+ "get_token_config",
259
+ "get_supported_tokens",
260
+ "is_token_supported",
261
+ "get_networks_by_token",
262
+ # CAIP-2 utilities
263
+ "parse_caip2_network",
264
+ "to_caip2_network",
265
+ "is_caip2_format",
266
+ "normalize_network",
267
+ # Response helpers (v1)
268
+ "create_402_response",
269
+ "create_402_headers",
270
+ "payment_required_response",
271
+ "Payment402Builder",
272
+ # Response helpers (v2)
273
+ "create_402_response_v2",
274
+ "create_402_headers_v2",
275
+ "payment_required_response_v2",
276
+ "Payment402BuilderV2",
277
+ # Facilitator constants and helpers
278
+ "DEFAULT_FACILITATOR_URL",
279
+ "get_facilitator_url",
280
+ "ALGORAND_FEE_PAYER_MAINNET",
281
+ "ALGORAND_FEE_PAYER_TESTNET",
282
+ "SOLANA_FEE_PAYER_MAINNET",
283
+ "SOLANA_FEE_PAYER_DEVNET",
284
+ "FOGO_FEE_PAYER_MAINNET",
285
+ "FOGO_FEE_PAYER_TESTNET",
286
+ "NEAR_FEE_PAYER_MAINNET",
287
+ "NEAR_FEE_PAYER_TESTNET",
288
+ "STELLAR_FEE_PAYER_MAINNET",
289
+ "STELLAR_FEE_PAYER_TESTNET",
290
+ "SUI_FEE_PAYER_MAINNET",
291
+ "SUI_FEE_PAYER_TESTNET",
292
+ "EVM_FACILITATOR_MAINNET",
293
+ "EVM_FACILITATOR_TESTNET",
294
+ "get_fee_payer",
295
+ "get_facilitator_address",
296
+ "requires_fee_payer",
297
+ "get_all_fee_payers",
298
+ "build_payment_info",
299
+ # ERC-8004 Trustless Agents
300
+ "Erc8004Client",
301
+ "ERC8004_EXTENSION_ID",
302
+ "ERC8004_CONTRACTS",
303
+ "ProofOfPayment",
304
+ "AgentIdentity",
305
+ "AgentRegistrationFile",
306
+ "ReputationSummary",
307
+ "FeedbackEntry",
308
+ "FeedbackParams",
309
+ "FeedbackRequest",
310
+ "FeedbackResponse",
311
+ "ReputationResponse",
312
+ "SettleResponseWithProof",
313
+ "build_erc8004_payment_requirements",
314
+ # Escrow & Refund
315
+ "EscrowClient",
316
+ "EscrowPayment",
317
+ "EscrowStatus",
318
+ "RefundRequest",
319
+ "RefundStatus",
320
+ "Dispute",
321
+ "DisputeOutcome",
322
+ "ReleaseConditions",
323
+ "RefundResponse",
324
+ "EscrowListResponse",
325
+ "can_release_escrow",
326
+ "can_refund_escrow",
327
+ "is_escrow_expired",
328
+ "escrow_time_remaining",
329
+ # Advanced Escrow (PaymentOperator) - available when eth_abi/web3/httpx installed
330
+ "ADVANCED_ESCROW_AVAILABLE",
331
+ "AdvancedEscrowClient",
332
+ "PaymentInfo",
333
+ "TaskTier",
334
+ "AuthorizationResult",
335
+ "TransactionResult",
336
+ "TIER_TIMINGS",
337
+ "BASE_MAINNET_CONTRACTS",
338
+ "OPERATOR_ABI",
339
+ ]
340
+
341
+ # Conditionally remove Advanced Escrow names from __all__ if not available
342
+ if not ADVANCED_ESCROW_AVAILABLE:
343
+ _advanced_names = {
344
+ "AdvancedEscrowClient", "PaymentInfo", "TaskTier",
345
+ "AuthorizationResult", "TransactionResult", "TIER_TIMINGS",
346
+ "BASE_MAINNET_CONTRACTS", "OPERATOR_ABI",
347
+ }
348
+ __all__ = [n for n in __all__ if n not in _advanced_names]