feat: Add batch payment support for settling multiple invoices in a single transaction #1729

Summary

Currently, paying multiple Request Network invoices requires executing a separate on-chain transaction for each invoice. For businesses processing 10-50+ invoices per month, this means:

• N separate approve + transfer calls
• N× gas costs
• Manual wallet interaction per invoice
• Extended settlement time

Proposal

Add batch payment support that allows users to settle multiple USDC invoices in a single on-chain transaction using multi-recipient batch transfer contracts.

How it works:

1. Fetch pending invoices from Request Network (filtered by payer address + currency)
2. Validate all recipients and amounts
3. Execute a single batchTransfer(token, recipients[], amounts[]) call
4. All payments are atomic — either all succeed or all revert

Gas savings:

• 10 invoices on Base: ~$0.10 individually → ~$0.02 batched (80% savings)
• 30 invoices on Ethereum: ~$45 individually → ~$10 batched (78% savings)

Implementation

I've built an integration module (spraay-request-network) that bridges Request Network's @requestnetwork/request-client.js with Spraay Protocol's batch transfer contracts deployed across Base, Ethereum, Arbitrum, Polygon, BNB Chain, and Avalanche.

The module provides:

• SpraayBatchPayer.payInvoices() — pay specific invoices by ID
• SpraayBatchPayer.payPendingInvoices() — auto-discover and batch-pay all pending USDC invoices
• batchPayViaGateway() — server-side / AI agent batch payments via API

I'd like to submit a PR adding a batch payment example to the monorepo and a reference to this integration in the documentation.

Use Cases

• Accounts payable automation — Settle a month's vendor invoices in one click
• Payroll — Pay all contractor invoices in a single batch
• DAO treasury — Batch-process approved grant payments
• AI agents — Programmatic invoice settlement via x402 micropayments

References

• Spraay Protocol: https://spraay.app
• Spraay Gateway API (115+ endpoints, 13+ chains): https://gateway.spraay.app
• Integration repo: https://github.com/plagtech/spraay-request-network
• Batch contract on Base: 0x1646452F98E36A3c9Cfc3eDD8868221E207B5eEC

Happy to discuss the approach and adjust based on your feedback. Would love to align this with the existing @requestnetwork/payment-processor patterns.