The SDK provides full coverage of core payment flows including authorization, release, charge, refund, and dispute resolution. This page documents the known limitations and planned improvements.
Stubbed Methods (Pending Subgraph)
Several payment query methods exist in the SDK but throw NotImplementedError because they require a subgraph/indexer for efficient querying. The on-chain contracts don’t store payment listings — state is derived from events.
The following methods are defined but will throw NotImplementedError when called. They are planned for implementation once a subgraph is deployed.
Client SDK (5 stubbed)
| Method | Description | Workaround |
|---|
getPaymentState(paymentInfo) | Get payment state enum | Query escrow contract events directly |
paymentExists(paymentInfoHash) | Check if payment exists | Use getPaymentAmounts() on merchant SDK |
isInEscrow(paymentInfoHash) | Check if in escrow | Use getPaymentAmounts() on merchant SDK |
getPaymentDetails(paymentInfoHash) | Get stored PaymentInfo | Reconstruct from AuthorizationCreated events |
getMyPayments() | List payer’s payments | Watch AuthorizationCreated events via subscriptions |
Merchant SDK (2 stubbed)
| Method | Description | Workaround |
|---|
getPaymentState(paymentInfo) | Get payment state enum | Query escrow contract events directly |
getReceiverPayments() | List receiver’s payments | Watch AuthorizationCreated events via subscriptions |
Arbiter SDK (1 stubbed)
| Method | Description | Workaround |
|---|
getPaymentState(paymentInfo) | Get payment state enum | Query escrow contract events directly |
All working refund, release, charge, freeze, and subscription methods function correctly. Only the payment listing and state query methods are stubbed.
API Constraints
EIP-155 Network Identifiers
Network configuration requires EIP-155 format strings, not chain ID numbers:
// Correct
const config = getNetworkConfig('eip155:84532');
// Incorrect - will return undefined
const config = getNetworkConfig(84532);
PaymentInfo Must Be Complete
All SDK methods require a complete PaymentInfo object. You cannot query by hash alone:
// Works - full PaymentInfo
const status = await client.getRefundStatus(paymentInfo, 0n);
// Not supported - hash-only queries require subgraph
// const state = await client.getPaymentStateByHash(hash);
No Express/Hono Middleware
The refundable() helper in @x402r/helpers is framework-agnostic. There is no dedicated Express or Hono middleware — use refundable() directly when constructing payment options.
Roadmap
See the Roadmap page for planned features and timeline.
Getting Updates
