>_ WDK / REFERENCE
SECURITY &
PRIVACY.
Operational security baseline for WDK + USDT0 integrations in production. Covers key management, nonce hygiene, signing security, logging practices, and incident response.
Threat Model
WDK settlement involves three security-critical assets: the private key that signs authorizations, the nonces that prevent replay, and the API key that authenticates to P402. Compromise of any one of these can result in fund loss.
| Threat | Impact | Mitigation |
|---|---|---|
| Private key leak | Attacker can sign unlimited transfers. | Use hardware wallets or HSMs. Never log or transmit private keys. Rotate immediately if suspected. |
| Nonce replay | Attacker replays a valid signature to settle again. | P402 tracks all nonces in the replay protection DB. Each nonce can only be settled once. |
| API key leak | Attacker can call settlement on your behalf. | SHA-256 hashed at rest. Rotate immediately via Dashboard → Settings → API Keys. Use scoped keys per environment. |
| Man-in-the-middle | Attacker intercepts and modifies settlement requests. | All P402 endpoints enforce HTTPS/TLS 1.3. EIP-712 signatures bind to exact authorization fields — modification breaks verification. |
| Expired authorization | User signs but settlement is delayed past validBefore. | Set validBefore to at least 1 hour from signing time. Always handle P402_SETTLEMENT_TIMEOUT errors. |
| Amount manipulation | Service charges more than declared. | P402 enforces amount matching at the facilitator layer. Requests where value ≠ maxAmountRequired are rejected. |
Key Management
For user-facing flows
When users sign their own authorizations (e.g. paying from their MetaMask wallet), the private key never leaves the browser. The WDK adapter calls the wallet's eth_signTypedData_v4 method. The signature is the only thing your backend receives.
Do / Don't
For server-side / agent flows
When your server or an autonomous agent signs authorizations, the private key lives in your infrastructure. Apply these practices:
Store the private key in an environment variable, never in code or config files that could be committed to version control.
P402 supports CDP Server Wallets (TEE-backed). The private key never leaves the hardware. Signing happens inside the secure enclave.
Use different signing keys for development, staging, and production. A dev key leak cannot drain production funds.
Build a rotation procedure before you go to production. Rotation must be zero-downtime: generate new key, update P402 wallet record, retire old key.
Nonce Hygiene
A nonce is a 32-byte random value embedded in every EIP-3009 authorization. P402 records every used nonce and rejects any settlement that reuses one — this is the replay protection mechanism.
Critical rule
Never reuse a nonce. Never generate nonces from sequential IDs, timestamps, or deterministic inputs. Always generate 32 cryptographically random bytes.
// Correct: 32 cryptographically random bytes
const nonce = '0x' + crypto.getRandomValues(new Uint8Array(32))
.reduce((hex, b) => hex + b.toString(16).padStart(2, '0'), '');
// Wrong: predictable, not 32 bytes of entropy
// const nonce = `0x${Date.now().toString(16)}`; // Too short
// const nonce = `0x${invoiceId.replace(/-/g, '')}`; // Deterministic
// const nonce = `0x${counter++}`; // SequentialLogging Practices
Settlement flows involve sensitive data. Log enough to debug incidents without creating a liability for your users.
| Data | Log it? | Why |
|---|---|---|
| receipt_id | Yes — always | Essential for support and reconciliation. |
| txHash | Yes — always | Needed to verify settlement on-chain. |
| walletAddress (from) | Yes — masked | Log first 6 + last 4 chars: 0xABCD...1234 |
| amount + asset | Yes — always | Needed for spend auditing. |
| signature | No | No value after settlement; storing creates unnecessary risk. |
| private key / nonce | Never | Catastrophic if leaked. |
| full authorization object | Dev/staging only | OK for debugging; never in production. |
| P402 API key | Never | Store only the last 4 chars for identification. |
Privacy Considerations
Settlement transactions are recorded on-chain and are permanently public. Communicate this clearly to your users.
Every settled transaction is visible on Base or Arbitrum block explorers. The from address, to address, amount, and timestamp are public permanently.
A wallet address does not directly identify a person, but on-chain activity can be linked to real identities through other data. Do not assume on-chain payments are anonymous.
P402 logs wallet addresses, API keys, and transaction metadata for fraud prevention and support. Review the P402 Privacy Policy before processing payments on behalf of EU/UK users (GDPR implications).
Store only what you need: receipt_id, txHash, amount, and masked wallet address. Never persist raw private keys, seed phrases, or full authorization objects.
Document how long you retain receipts, audit logs, and payment events. Follow applicable regulations for your jurisdiction and user base.
Incident Response
If you suspect a key compromise or unauthorized settlement, act immediately:
For P402 API keys: Dashboard → Settings → API Keys → Revoke. Generate a new key immediately. For signing keys: generate a new wallet, update all references, and drain the old wallet to the new one.
Pull settlement history from Dashboard → Transactions. Look for unexpected wallet addresses in the "from" field or amounts you did not authorize.
If you have admin access, use POST /api/v1/admin/security with action: "pause" to halt all settlements for your account while you investigate.
Email security@p402.io with incident details. Include the compromised key's last 4 chars, time range of suspected activity, and any txHashes you believe are unauthorized.