Testnet API - Build Any Financial Flow

Think of Testnet API as your Lego blocks for financial flows. Each endpoint is a building block that you can combine to create different payment scenarios - from simple fiat-to-crypto onramps to complex cross-border transfers.

🎯 What Can You Build?

Instead of rigid, predefined flows, you get flexible building blocks that work together:

• Fiat Entry Points: Convert real money into USDC
• Transfer Bridges: Move money between wallets and chains
• Fiat Exit Points: Convert USDC back to real money
• Tracking Tools: Monitor and log your transactions

🧩 Your Building Blocks

💰 Money Input Blocks

• POST /testnet/onramp - Bring fiat money into the system as USDC
• POST /testnet/deposit/confirm - Convert USDC deposits into fiat wallets

🔄 Transfer & Bridge Blocks

• POST /testnet/onrampwallet - Move money between internal wallets
• POST /testnet/send-usd - Send USD across borders using USDC as bridge
• POST /testnet/send-usdc-direct - Send USDC directly to any blockchain address

📊 Discovery & Management Blocks

• GET /testnet/listwalletUsd - Find other users' wallets for testing
• GET /testnet/mywalletUsd - Get your own USD wallet info
• POST /testnet/log-user-transfer - Track external wallet transactions

⚙️ Infrastructure Blocks

• POST /testnet/chain - Check which blockchain networks are available

🏗️ Common Building Patterns

Pattern 1: "I want to test fiat-to-crypto onramp"

Fiat Money → onramp → USDC on blockchain

Use: /testnet/onramp

Pattern 2: "I want to test cross-border money transfer"

USD Wallet → send-usd → USDC bridge → USD Wallet (different country)

Use: /testnet/send-usd

Pattern 3: "I want to test crypto-to-fiat offramp"

USDC on blockchain → deposit/confirm → Fiat in wallet

Use: /testnet/deposit/confirm

Pattern 4: "I want to test complete money journey"

Fiat → onramp → USDC → transfer → USDC → offramp → Fiat

Use: Combine multiple endpoints

---

🔧 Building Block Details

Fiat to USDC Onramp

POST/api/testnet/onramp

Convert Fiat Money to USDC

Your first building block - converts real money (IDR, USD, etc.) into USDC that lives on the Sepolia testnet. Perfect for testing how users would deposit money into your crypto system.

Parameters

amount_idrnumberrequired

How much Indonesian Rupiah to convert (use your local currency)

wallet_idstringrequired

Which wallet should receive the USDC

Request Body

{
  "amount_idr": 150000,
  "wallet_id": "wallet_123456"
}

Response

200Money successfully converted to USDC

{
  "success": true,
  "message": "Your IDR is now USDC on blockchain!",
  "transaction_id": "txn_testnet_1234567890",
  "amount_idr": 150000,
  "amount_usdc": 10,
  "exchange_rate": 15000,
  "wallet_address": "0x153c26a547C35009Ba3fE69a1F9f431B089bB301",
  "network": "sepolia",
  "status": "completed"
}

Cross-Border USD Transfer

POST/api/testnet/send-usd

Send USD Across Borders via USDC

Your cross-border magic block - takes USD from one wallet, converts to USDC, sends it across blockchain, then converts back to USD in recipient's wallet. Perfect for testing international money transfers.

Parameters

from_wallet_idstringrequired

Sender's USD wallet (where money comes from)

to_wallet_idstringrequired

Recipient's USD wallet (where money goes to)

amountnumberrequired

How much USD to send

Request Body

{
  "from_wallet_id": "wallet_usd_alice",
  "to_wallet_id": "wallet_usd_bob",
  "amount": 75
}

Response

200Money successfully sent across borders

{
  "success": true,
  "message": "USD sent via USDC bridge successfully",
  "transaction_id": "txn_usd_1234567890",
  "from_wallet_id": "wallet_usd_alice",
  "to_wallet_id": "wallet_usd_bob",
  "amount_usd": 75,
  "amount_usdc": 75,
  "recipient_address": "0x153c26a547C35009Ba3fE69a1F9f431B089bB301",
  "step_log": {
    "1_convert_usd_to_usdc": "completed",
    "2_send_usdc_onchain": "completed",
    "3_credit_usd_to_recipient": "completed"
  },
  "status": "completed"
}

USDC to Fiat Conversion

POST/api/testnet/deposit/confirm

Convert USDC Back to Fiat Money

Your off-ramp block - takes USDC that someone received and converts it back into real fiat money in their wallet. Complete the money journey from crypto back to traditional currency.

Parameters

user_idnumberrequired

Which user is receiving the money

wallet_addressstringrequired

Where the USDC was received

amountnumber

How much USDC to convert (auto-detected if not provided)

Request Body

{
  "user_id": 123,
  "wallet_address": "0x153c26a547C35009Ba3fE69a1F9f431B089bB301",
  "amount": 100
}

Response

200USDC successfully converted to fiat

{
  "success": true,
  "message": "USDC converted to fiat and credited to wallet",
  "deposit_id": "dep_1234567890",
  "user_id": 123,
  "amount_usdc": 100,
  "amount_fiat": 1500000,
  "currency": "IDR",
  "exchange_rate": 15000,
  "status": "completed"
}

Direct USDC Transfer

POST/api/testnet/send-usdc-direct

Send USDC Directly to Any Address

Your direct blockchain block - sends USDC straight to any Ethereum address without wallet-to-wallet complexity. Perfect for testing direct crypto payments.

Parameters

evm_addressstringrequired

Any Ethereum-compatible wallet address

amountnumberrequired

How much USDC to send

Request Body

{
  "evm_address": "0x987654321098765432109876543210987654321",
  "amount": 50
}

Response

200USDC sent directly to address

{
  "success": true,
  "message": "USDC sent directly to blockchain address",
  "transaction_id": "txn_direct_1234567890",
  "evm_address": "0x987654321098765432109876543210987654321",
  "amount": 50,
  "currency": "USDC",
  "network": "sepolia",
  "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef12",
  "status": "completed"
}

Wallet Discovery

GET/api/testnet/listwalletUsd

Find Other Users' Wallets for Testing

Your testing helper block - discover other users' USD wallets so you can test transfers between different accounts. Essential for multi-user testing scenarios.

Response

200List of available test wallets

{
  "wallets": [
    {
      "wallet_id": "wallet_usd_alice",
      "username": "alice_doe",
      "address": "0x987654321098765432109876543210987654321",
      "country_code": "SG"
    },
    {
      "wallet_id": "wallet_usd_bob",
      "username": "bob_smith",
      "address": "0x456789012345678901234567890123456789012",
      "country_code": "AU"
    }
  ]
}

Get My Wallet

GET/api/testnet/mywalletUsd

Get Your Own USD Wallet Info

Your wallet info block - get details about your own USD wallet including balance limits and status. Essential starting point for any wallet operations.

Response

200Your wallet information

{
  "wallet": {
    "wallet_id": "wallet_usd_123",
    "address": "0x123456789012345678901234567890123456789",
    "currency": "USD",
    "wallet_status": "ACTIVE",
    "balance_limit": 10000,
    "created_at": "2024-01-10T08:00:00Z"
  }
}

---

🔐 Security & Smart Contract Integration

Why Hardcoded Test Addresses?

For testing safety, certain endpoints use hardcoded recipient addresses instead of user-provided ones:

Security Benefits:

• No risk of user funds being lost
• No need to handle user private keys
• Predictable testing environment
• Production-ready security patterns

Production vs Testing:

// 🧪 Testing Mode (uses safe hardcoded address)
const testResult = await testnet.onrampTestnet({
  amount_idr: 150000,
  wallet_id: "my_wallet"  
});
// → USDC goes to: 0x153c26a547C35009Ba3fE69a1F9f431B089bB301

// 🚀 Production Mode (user provides their address)
const prodResult = await testnet.sendUsdcDirect({
  evm_address: "0xUserProvidedAddress", // User's own wallet
  amount: 50.00
});
// → USDC goes to: User's specified address

Smart Contract Integration

Testnet operates on Sepolia network with these contracts:

Contract Type	Address	Purpose
USDC Token	0x9BF350fBaaA8c7200990B051809334c90778f435	ERC-20 USDC transfers
Bridge Contract	0x432a3Ab53BEe8657cD5E26Bd9A7251Bbd19B3Fb1	Cross-chain operations
Test Recipient	0x153c26a547C35009Ba3fE69a1F9f431B089bB301	Safe testing wallet

Network Details:

• Chain ID: 11155111 (Sepolia)
• RPC URL: https://sepolia.infura.io/v3/...
• Explorer: https://sepolia.etherscan.io/

🚀 Building Complete Flows

Flow 1: Complete Fiat-to-Fiat Journey

// Test the full money journey: IDR → USDC → USD
async function testCompleteJourney() {
  // Step 1: Convert fiat to USDC
  const onramp = await testnet.onrampTestnet({
    amount_idr: 300000,  // 300k IDR
    wallet_id: "my_wallet"
  });
  
  // Step 2: Convert USDC back to fiat
  const offramp = await testnet.confirmDeposit({
    user_id: 123,
    wallet_address: onramp.wallet_address,
    amount: onramp.amount_usdc
  });
  
  console.log(`Journey complete: ${onramp.amount_idr} IDR → ${onramp.amount_usdc} USDC → ${offramp.amount_fiat} ${offramp.currency}`);
}

Flow 2: Cross-Border Transfer Testing

// Test international money transfer
async function testCrossBorderTransfer() {
  // Step 1: Get your wallet and find recipient
  const myWallet = await testnet.getMyUsdWallet();
  const otherWallets = await testnet.getUserWalletListUsd();
  
  // Step 2: Send money across borders
  const transfer = await testnet.sendUsd({
    from_wallet_id: myWallet.wallet.wallet_id,
    to_wallet_id: otherWallets.wallets[0].wallet_id,
    amount: 100.00
  });
  
  console.log("Money sent from", myWallet.wallet.address);
  console.log("To", otherWallets.wallets[0].username, "in", otherWallets.wallets[0].country_code);
  console.log("Transfer steps:", transfer.step_log);
}

Advanced Security Testing

// Test security patterns and smart contract integration
async function testSecurityIntegration() {
  console.log('🔐 Testing security and smart contract patterns...');
  
  // 1. Safe testing with controlled addresses
  const safeTest = await testnet.onrampTestnet({
    amount_idr: 150000,
    wallet_id: "test_wallet"
  });
  
  console.log(`💰 Safe onramp test completed:`);
  console.log(`   USDC amount: ${safeTest.amount_usdc}`);
  console.log(`   Safe address: ${safeTest.wallet_address}`);
  console.log(`   Network: ${safeTest.network}`);
  
  // 2. Direct address control (production pattern)
  const directSend = await testnet.sendUsdcDirect({
    evm_address: "0x987654321098765432109876543210987654321",
    amount: 25.00
  });
  
  console.log(`🎯 Direct USDC transfer:`);
  console.log(`   Amount: ${directSend.amount} USDC`);
  console.log(`   To address: ${directSend.evm_address}`);
  console.log(`   Transaction: ${directSend.tx_hash}`);
  
  // 3. Smart contract details
  console.log(`⛓️ Smart contract integration:`);
  console.log(`   USDC Contract: 0x9BF350fBaaA8c7200990B051809334c90778f435`);
  console.log(`   Bridge Contract: 0x432a3Ab53BEe8657cD5E26Bd9A7251Bbd19B3Fb1`);
  console.log(`   Chain ID: 11155111 (Sepolia)`);
  
  return { safeTest, directSend };
}

🎯 When to Use Which Block

Starting a Test Session

1. Get your wallet: GET /testnet/mywalletUsd
2. Check available networks: POST /testnet/chain
3. Find test partners: GET /testnet/listwalletUsd

Testing Onramp Scenarios

• Fiat to crypto: POST /testnet/onramp
• External deposit tracking: POST /testnet/log-user-transfer

Testing Transfer Scenarios

• Internal transfers: POST /testnet/onrampwallet
• Cross-border fiat: POST /testnet/send-usd
• Direct crypto: POST /testnet/send-usdc-direct

Testing Offramp Scenarios

• Crypto to fiat: POST /testnet/deposit/confirm

💡 Pro Tips for Developers

Testing Strategy

// Always start with wallet discovery
const setup = async () => {
  const chains = await testnet.getAvailableChains();
  const myWallet = await testnet.getMyUsdWallet();
  const testWallets = await testnet.getUserWalletListUsd();
  
  console.log("Test environment ready!");
  console.log("Active chains:", chains.chains.filter(c => c.active));
  console.log("My wallet:", myWallet.wallet.wallet_id);
  console.log("Test partners:", testWallets.wallets.length);
};

Error Handling

// Always wrap in try-catch
try {
  const result = await testnet.onrampTestnet({
    amount_idr: 150000,
    wallet_id: "my_wallet"
  });
} catch (error) {
  if (error.message.includes('Missing required fields')) {
    console.log("Check your parameters");
  } else if (error.message.includes('wallet not found')) {
    console.log("Wallet doesn't exist - create one first");
  }
}

Debugging Flows

// Use step logs for complex flows
const transfer = await testnet.sendUsd({
  from_wallet_id: "alice",
  to_wallet_id: "bob", 
  amount: 50
});

// Check each step completed successfully
Object.entries(transfer.step_log).forEach(([step, status]) => {
  console.log(`${step}: ${status}`);
});

---

🌍 Supported Currencies & Networks

Fiat Currencies

Based on your user's country, the system supports:

• IDR (Indonesia) - Primary testing currency
• USD (United States) - International standard
• SGD (Singapore) - Regional testing
• AUD (Australia) - Regional testing
• VND (Vietnam) - Regional testing
• INR (India) - Regional testing

Blockchain Networks

• Sepolia Testnet - Active for all operations
• Other EVM Networks - Available but currently inactive

Test Environment Constants

• Exchange Rate: 1 USDC = 15,000 IDR (hardcoded for testing)
• Test Recipient Wallet: 0x153c26a547C35009Ba3fE69a1F9f431B089bB301 (Safe test wallet for receiving funds)
• Network: Sepolia Testnet
• Token Standard: ERC-20 USDC
• USDC Contract: 0x9BF350fBaaA8c7200990B051809334c90778f435 (Sepolia)

Security Model

• Never ask users for private keys - All testnet operations use safe, hardcoded addresses
• Test wallet controlled by BRDZ - Ensures funds don't get lost during testing
• Production-ready code - Same security patterns work for mainnet deployment

---

Security Best Practices

Never ask users for private keys in testing or production. Use hardcoded safe addresses for testing, and let users specify their own addresses for production. This testnet demonstrates production-ready security patterns.

Smart Contract Interactions

All USDC operations interact with the ERC-20 contract at 0x9BF350fBaaA8c7200990B051809334c90778f435 on Sepolia. Bridge operations use contract 0x432a3Ab53BEe8657cD5E26Bd9A7251Bbd19B3Fb1. These are testnet-only addresses.

Production Migration

The same security patterns and API structure work for mainnet deployment. Only contract addresses and RPC URLs need to change when moving from testnet to production.