Testnet Guide

Blocky402 testnet is fully operational and ready for development and testing. No API key required!

Testnet Status

✅ Fully Operational

• Open access (no authentication required)
• Perfect for development and testing
• Real blockchain transactions on testnets

Base URLs

• Hosted Testnet: https://api.testnet.blocky402.com
• Local Development: http://localhost:3002

Supported Testnet Networks

The hosted facilitator advertises these networks at GET /supported:

1. Polygon Amoy (eip155:80002) - EVM testnet
2. Solana Devnet (solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1) - Solana testnet
3. Hedera Testnet (hedera:testnet) - Hedera Hashgraph testnet

Additional networks (Base, Arbitrum, Optimism, Avalanche, Ethereum) are implemented and can be enabled when self-hosting. See Networks & Assets for detailed network information.

No Authentication Required

Unlike mainnet, testnet requires no API key. Simply make requests to the API:

# No headers needed!
curl http://localhost:3002/supported

// No authentication required
const response = await fetch('http://localhost:3002/supported');
const data = await response.json();

Rate Limiting

Testnet uses per-IP rate limiting:

• Limit: 100 requests per minute per IP
• Burst: 10 requests
• Type: In-memory (resets on server restart)

This is more lenient than mainnet to allow for development and testing.

Getting Testnet Tokens

You’ll need testnet tokens to make payments. Here are faucets for each network:

Polygon Amoy

• Polygon Faucet
• Get POL for gas and USDC for payments

Solana Devnet

• Solana Faucet
• Get SOL for fees and USDC for payments

Hedera Testnet

• Hedera Portal Faucet
• Get testnet HBAR for fees and payments

Testnet vs Mainnet

Quick Testnet Example

Here’s a complete testnet example:

const API_BASE = 'http://localhost:3002';
 
// 1. Check supported networks (no auth needed!) and pick the Hedera fee-payer
// the facilitator advertises.
const supported = await fetch(`${API_BASE}/supported`).then((r) => r.json());
const hederaKind = supported.kinds.find((k) => k.network === 'hedera:testnet');
const feePayer = hederaKind.extra?.feePayer ?? supported.signers?.['hedera:*']?.[0];
 
// 2. Build the v2 body. paymentPayload comes from signing with an
// @x402 client SDK; the shape shown is what flows over HTTP.
const paymentRequirements = {
  scheme: 'exact',
  network: 'hedera:testnet',
  amount: '100000',                // 100,000 tinybars = 0.001 HBAR
  payTo: '0.0.8011510',
  maxTimeoutSeconds: 300,
  asset: '0.0.0',                  // HBAR (use a token id for HTS payments)
  extra: { feePayer },
};
const body = {
  x402Version: 2,
  paymentPayload, // produced by your @x402/hedera client (or @x402/evm, @x402/svm)
  paymentRequirements,
};
 
// 3. Verify
const verification = await fetch(`${API_BASE}/verify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(body),
}).then((r) => r.json());
console.log('Valid:', verification.isValid, '| Payer:', verification.payer);
 
// 4. Settle (if valid)
if (verification.isValid) {
  const settlement = await fetch(`${API_BASE}/settle`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  }).then((r) => r.json());
  console.log('Transaction:', settlement.transaction);
}

Local Development

To run Blocky402 locally for testnet development:

# Clone the repository
git clone https://github.com/blockydevs/blocky402.git
cd blocky402/apps/api
 
# Install dependencies
pnpm install
 
# Set up environment
cp env.example .env
# Edit .env with your configuration
 
# Start PostgreSQL (using Docker)
docker-compose up -d postgres
 
# Start the API
pnpm run start:dev

The API will be available at http://localhost:3002.

Testing Your Integration

1. Start with /supported: Verify which networks are available
2. Test /verify: Verify payment payloads before settling
3. Test /settle: Settle payments on testnet
4. Monitor transactions: Check your transactions on testnet explorers

Testnet Explorers

View your testnet transactions:

• Polygon Amoy: Amoy PolygonScan
• Solana Devnet: Solana Explorer
• Hedera Testnet: HashScan Testnet

Best Practices

1. Use testnet for development: Always test on testnet before mainnet
2. Monitor rate limits: Stay within 100 requests/minute
3. Verify before settling: Always verify payments before settling
4. Check transaction status: Use blockchain explorers to verify settlements
5. Test error cases: Test invalid payments, expired payments, etc.

Migration to Mainnet

When mainnet launches:

1. You’ll need an API key (see Authentication)
2. Rate limits will be per-key instead of per-IP
3. You’ll use real stablecoins instead of testnet tokens
4. Networks will be mainnet versions (e.g., eip155:137 instead of eip155:80002)

Need Help?

• Check the Quickstart Guide for step-by-step instructions
• Review API Reference for endpoint details
• See Code Examples for more examples
• Open an issue on GitHub