* feat: add batch-settlement implementation to Go SDK * feat: add batch-settlement examples for go sdk * feat: updated typescript examples to match go examples * feat: add e2e testing for batch-settlement in go * Batch-settlement: go-ts parity (#2227) * fix PendingRequest and refund cleanup * fix lint * remove duplicate payer info from storage * fix PAYMENT-RESPONSE field ordering * clean up comments * consolidate ProcessSettlementWithExtensions into ProcessSettlement --------- Co-authored-by: phdargen <p.dargent@cern.ch>
Integration Tests
These integration tests verify the complete x402 payment flows with real mechanism implementations. The EVM and SVM tests can make real on-chain transactions when configured with private keys.
Test Overview
Core Integration Tests (Always Run)
- โ TestCoreIntegration - Core x402 client/service/facilitator flow (mock cash)
- โ TestHTTPIntegration - HTTP layer integration (mock cash)
Mechanism Integration Tests (Require Configuration)
- ๐ TestEVMIntegrationV2 - Full EVM V2 payment flow (Base Sepolia)
- ๐ TestEVMIntegrationV1 - Full EVM V1 payment flow (Base Sepolia)
- ๐ TestSVMIntegrationV2 - Full SVM V2 payment flow (Solana Devnet)
- ๐ TestSVMIntegrationV1 - Full SVM V1 payment flow (Solana Devnet)
Batch-Settlement (Batched) Integration Tests (Require Configuration)
EVM batched mechanism tests in evm_batch_settlement_test.go. All tests
issue real Base Sepolia transactions and skip when env vars are missing.
- ๐ TestBatchSettlementIntegration_DepositThenVoucher โ direct API: deposit + follow-up voucher
- ๐ TestBatchSettlementIntegration_HTTPMiddleware โ full HTTP middleware end-to-end
- ๐ TestBatchSettlementIntegration_MultiVoucherClaimSettle โ 4 requests + manager.Claim + manager.Settle
- ๐ TestBatchSettlementIntegration_RefundPartial โ partial refund leaves channel open
- ๐ TestBatchSettlementIntegration_RefundDrainedChannelShortCircuit โ local short-circuit on drained channel
- ๐ TestBatchSettlementIntegration_RefundNonRecoverableFastFail โ
amount_exceeds_balanceerrors immediately - ๐ TestBatchSettlementIntegration_RefundRecoverableRetryExhaustion โ recoverable 402 โ retry โ exhaust
- ๐ TestBatchSettlementIntegration_AutoClaimTick โ
ClaimIntervalSecstriggers OnClaim - ๐ TestBatchSettlementIntegration_AutoClaimAndSettleTick โ both OnClaim and OnSettle fire
- ๐ TestBatchSettlementIntegration_WithdrawalPendingRefund โ pending-withdraw detection + manager.Refund
Tests marked with ๐ require environment variables and will skip if not configured.
Running Tests
Without Configuration (Core Tests Only)
make test-integration
Output:
โ
TestCoreIntegration - PASS
โ
TestHTTPIntegration - PASS
โญ๏ธ TestEVMIntegrationV2 - SKIP (env vars not set)
โญ๏ธ TestEVMIntegrationV1 - SKIP (env vars not set)
โญ๏ธ TestSVMIntegrationV2 - SKIP (env vars not set)
โญ๏ธ TestSVMIntegrationV1 - SKIP (env vars not set)
With Configuration (All Tests + Real Transactions)
# Set environment variables
source .env
# Run integration tests
make test-integration
Output:
โ
TestCoreIntegration - PASS
โ
TestHTTPIntegration - PASS
โ
TestEVMIntegrationV2 - PASS (real Base Sepolia transaction)
โ
TestEVMIntegrationV1 - PASS (real Base Sepolia transaction)
โ
TestSVMIntegrationV2 - PASS (real Solana Devnet transaction)
โ
TestSVMIntegrationV1 - PASS (real Solana Devnet transaction)
Configuration
Create a .env file in the go/ directory:
# EVM Configuration (Base Sepolia)
EVM_CLIENT_PRIVATE_KEY=<hex_private_key_without_0x>
EVM_FACILITATOR_PRIVATE_KEY=<hex_private_key_without_0x>
EVM_RESOURCE_SERVER_ADDRESS=<0x_ethereum_address>
# Batch-Settlement reuses the EVM_* keys above (EVM_RESOURCE_SERVER_ADDRESS is the payee)
EVM_AUTHORIZER_PRIVATE_KEY=<hex_private_key> # optional, defaults to EVM_FACILITATOR_PRIVATE_KEY
EVM_RPC_URL=https://sepolia.base.org # optional, defaults to Base Sepolia public RPC
# SVM Configuration (Solana Devnet)
SVM_CLIENT_PRIVATE_KEY=<base58_private_key>
SVM_FACILITATOR_PRIVATE_KEY=<base58_private_key>
SVM_FACILITATOR_ADDRESS=<base58_solana_address>
SVM_RESOURCE_SERVER_ADDRESS=<base58_solana_address>
Required Setup
EVM (Base Sepolia)
- Client Wallet: Must have USDC balance on Base Sepolia
- Facilitator Wallet: Must have ETH for gas fees
- Resource Server Address: Destination for payments
- Network: Base Sepolia (ChainID: 84532)
- Token: USDC (
0x036CbD53842c5426634e7929541eC2318f3dCF7e)
Get Testnet USDC:
- Faucet: https://faucet.circle.com/
- Or bridge from Sepolia to Base Sepolia
SVM (Solana Devnet)
- Client Wallet: Must have USDC balance on Solana Devnet
- Client ATA: Must have Associated Token Account for USDC
- Resource Server ATA: Must have Associated Token Account for USDC
- Facilitator Wallet: Must have SOL for transaction fees
- Network: Solana Devnet
- Token: USDC (
4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU)
Get Testnet USDC:
# Get SOL from faucet
solana airdrop 2 <your_address> --url devnet
# Create ATA for USDC
spl-token create-account 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU --url devnet
# Get USDC from faucet (if available)
# Or use Solana Devnet USDC faucet
What the Tests Do
EVM Integration Tests
- โ Creates real client with private key
- โ Creates real facilitator with private key
- โ Builds payment requirements (0.001 USDC)
- โ Client creates EIP-3009 authorization and signs with EIP-712
- โ Service verifies authorization signature
- โ Service validates amount, recipient, nonce
- โ Facilitator submits transferWithAuthorization on-chain
- โ Waits for transaction confirmation
- โ Verifies transaction succeeded
SVM Integration Tests
- โ Creates real client with private key
- โ Creates real facilitator with private key
- โ Builds payment requirements (0.001 USDC)
- โ
Client creates Solana transaction with:
- Compute budget instructions
- SPL Token TransferChecked instruction
- โ Client partially signs transaction
- โ Service decodes and validates transaction structure
- โ Service validates compute prices, amount, mint, recipient
- โ Facilitator co-signs transaction
- โ Facilitator submits transaction to Solana Devnet
- โ Waits for transaction confirmation (with retries)
- โ Verifies transaction succeeded
Test Output Examples
EVM Test Output (With Configuration)
=== RUN TestEVMIntegrationV2
evm_test.go:400: โ
Payment verified successfully from 0x1234...
evm_test.go:429: โ
Payment settled successfully! Transaction: 0xabcd...
--- PASS: TestEVMIntegrationV2 (5.2s)
SVM Test Output (With Configuration)
=== RUN TestSVMIntegrationV2
svm_test.go:288: โ
Payment payload created with transaction: 512 bytes
svm_test.go:309: โ
Payment verified successfully from ABC123...
svm_test.go:336: โ
Payment settled successfully! Transaction: 5J7...
svm_test.go:337: View on Solana Explorer: https://explorer.solana.com/tx/5J7.../devnet
--- PASS: TestSVMIntegrationV2 (8.1s)
Troubleshooting
EVM Tests Failing
Error: "insufficient balance"
- โก๏ธ Ensure client wallet has USDC on Base Sepolia
- โก๏ธ Use Circle faucet: https://faucet.circle.com/
Error: "invalid signature"
- โก๏ธ Check EVM_CLIENT_PRIVATE_KEY is correct (no 0x prefix)
- โก๏ธ Verify ChainID is 84532 (Base Sepolia)
Error: "nonce already used"
- โก๏ธ Wait a bit and retry (nonce was used in previous test)
- โก๏ธ Or use a new nonce (automatic in code)
SVM Tests Failing
Error: "ATA not found"
- โก๏ธ Create Associated Token Accounts for USDC:
spl-token create-account 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU --url devnet - โก๏ธ Must create ATAs for both client and resource server addresses
Error: "insufficient lamports"
- โก๏ธ Get SOL from devnet faucet:
solana airdrop 2 <address> --url devnet
Error: "transaction simulation failed"
- โก๏ธ Check all ATAs exist
- โก๏ธ Check client has USDC balance
- โก๏ธ Check facilitator has SOL for fees
Security Notes
โ ๏ธ NEVER commit private keys to git
โ ๏ธ Use .env file and ensure it's in .gitignore
โ ๏ธ Only use testnet keys with no real value
โ ๏ธ These tests use devnet/testnet networks only
CI/CD Integration
For CI/CD pipelines, you can:
- Skip tests by default (no env vars)
- Run with secrets in protected branches:
env: EVM_CLIENT_PRIVATE_KEY: ${{ secrets.EVM_CLIENT_PRIVATE_KEY }} EVM_FACILITATOR_PRIVATE_KEY: ${{ secrets.EVM_FACILITATOR_PRIVATE_KEY }} # ... other secrets
Comparison with TypeScript
The Go integration tests match the TypeScript implementation:
| Feature | TypeScript | Go | Status |
|---|---|---|---|
| Real signers | โ | โ | Implemented |
| On-chain transactions | โ | โ | Implemented |
| Environment variables | โ | โ | Implemented |
| Skip if not configured | โ | โ | Implemented |
| EVM (Base Sepolia) | โ | โ | Implemented |
| SVM (Solana Devnet) | โ | โ | Implemented |
Performance
Without Configuration: ~1.5s (skips mechanism tests) With Configuration: ~10-20s (includes real blockchain transactions)
Next Steps
To run full on-chain tests:
- Generate test wallets
- Fund wallets with testnet tokens
- Create ATAs (for SVM)
- Set environment variables
- Run
make test-integration - Watch real transactions execute! ๐