@waffo/waffo-node 2.5.1 → 2.6.0

package/README.md

@@ -1,6 +1,6 @@
 # Waffo Node.js SDK
 
-<!-- Synced with waffo-sdk/README.md @ commit c23c86f -->
+<!-- Synced with waffo-sdk/README.md @ commit 738f4ca -->
 
 **English** | [中文](README_CN.md)
 
@@ -678,6 +678,37 @@ if (response.isSuccess()) {
 }
 ```
 
+### Wallet Address Inquiry (x402)
+
+Inquire the on-chain stablecoin receiving address for an x402 payment. The response returns the target network, the on-chain token contract, and the Waffo platform wallet address to send funds to. Phase 1 supports `USDC`.
+
+```typescript
+// paymentRequestId: unique idempotency key for this inquiry
+// orderCurrency: settlement currency of the order (Phase 1 supports USDC)
+// merchantInfo is auto-injected from config if not provided
+const response = await waffo.wallet().inquiry({
+  paymentRequestId: 'unique-request-id',
+  orderCurrency: 'USDC',
+});
+
+if (response.isSuccess()) {
+  const data = response.getData();
+  console.log('Network:', data?.network); // CAIP-2 network id, e.g. eip155:8453 (Base mainnet)
+  console.log('Asset:', data?.asset);     // on-chain token contract address
+  console.log('Pay to:', data?.payTo);    // Waffo platform receiving wallet address
+} else {
+  console.error('Wallet inquiry failed:', response.getCode(), response.getMessage());
+}
+```
+
+#### Wallet Inquiry Response Fields
+
+| Field | Description |
+|-------|-------------|
+| `network` | CAIP-2 network id (Phase 1: `eip155:8453`, Base mainnet) |
+| `asset` | On-chain token contract address for the network + currency |
+| `payTo` | Waffo platform receiving wallet address (send funds here) |
+
 ## Webhook Handling
 
 Waffo pushes payment results, refund results, subscription status changes, and more via webhooks.
@@ -862,6 +893,8 @@ The following examples show the actual payload structure for each notification t
 }
 ```
 
+For x402 stablecoin payments, `PAYMENT_NOTIFICATION.result` also includes `x402Info` with `x402Request`, `paymentSignatureHeader`, and `x402Response`.
+
 #### SUBSCRIPTION_STATUS_NOTIFICATION / SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION
 
 These two notification types share the same payload structure:
@@ -1294,7 +1327,7 @@ Error codes are classified by first letter:
 | `S0004` | Response Signature Verification Failed | `ApiResponse.error()` | Check Waffo public key config, contact Waffo |
 | `S0005` | Request Serialization Failed | `ApiResponse.error()` | Check request parameter format |
 | `S0006` | SDK Unknown Error | `ApiResponse.error()` | Check logs, contact technical support |
-| `S0007` | Invalid Private Key | `WaffoError` | Check if private key is valid Base64 PKCS8 DER or unencrypted PKCS8 PEM format |
+| `S0007` | Invalid Private Key | `WaffoError` | Check if private key is valid Base64 encoded PKCS8 format |
 
 > **Important**: `S0001` and `E0001` (returned by server) indicate **unknown status**. Do not close order directly! Should call query API or wait for webhook to confirm actual status.