Skip to main content

Test Token Faucet

The GTX DEX Test Token Faucet provides developers and users with test tokens needed for development, testing, and experimentation across multiple testnets including GTX devnet and Base Sepolia.

Overview

The faucet system allows users to request test tokens with built-in rate limiting and balance management:
  • Multiple Token Support - Request various test tokens
  • Cooldown Periods - Prevents spam and ensures fair distribution
  • Balance Tracking - Monitor both user and faucet balances
  • Request History - Track all previous token requests
  • Automatic Distribution - Instant token delivery upon request

Development Testing

Get tokens for smart contract testing and development

Trading Practice

Practice trading strategies with test tokens

Integration Testing

Test API integrations and trading functionality

UI/UX Testing

Test frontend interfaces and user workflows

Available Test Tokens

The faucet provides the following test tokens on GTX devnet:

Core Trading Tokens

TokenSymbolAddressDecimalsAmount per Request
Mock USD CoinMUSDC0xC004...CffF61,000 MUSDC
Mock Wrapped EthereummWETH0xbb66...e99185 mWETH
Mock Wrapped BitcoinmWBTC0xdDbe...A29380.1 mWBTC
Mock ChainlinkLINK0x24b1...D901E18100 LINK
Mock PepePEPE0x7FB2...D147874181,000,000 PEPE
Token addresses are shortened for display. Full addresses are available in the smart contracts documentation.

Using the Faucet

Step-by-Step Guide

1

Connect Wallet

Connect your wallet to the GTX devnet
2

Select Token

Choose which test token you want to request from the dropdown
3

Check Cooldown

Verify you’re not in cooldown period from previous requests
4

Request Tokens

Click “Request Tokens” to submit your request
5

Confirm Transaction

Approve the transaction in your wallet
6

Receive Tokens

Tokens are automatically transferred to your wallet

Faucet Interface Features

Smart Token Picker
  • Visual display of available tokens
  • Real-time balance information
  • Token symbol and contract address
  • Amount per request clearly shown
// Example token selection
{
  token: "0xC004514803F58b09eee24471BC9EfF3D1087CffF",
  symbol: "MUSDC",
  amount: "1000",
  decimals: 6
}
Real-time Balance Display
  • Your current token balance
  • Faucet remaining balance
  • Last request timestamp
  • Next eligible request time
// Balance information
{
  userBalance: "2,500.00 MUSDC",
  faucetBalance: "500,000.00 MUSDC", 
  lastRequest: "2024-01-15T10:30:00Z",
  nextEligible: "2024-01-15T11:30:00Z"
}
Transaction Tracking
  • Complete history of your requests
  • Transaction hashes and timestamps
  • Request status and amounts
  • Explorer links for verification

Rate Limiting & Cooldowns

Cooldown System

The faucet implements cooldown periods to ensure fair distribution:
Request Limitations
  • Cooldown Period: 1 hour between requests per address
  • Daily Limit: Maximum requests per 24-hour period
  • Token Specific: Cooldowns apply per token type
  • Fair Distribution: Prevents spam and hoarding
// Cooldown calculation
const COOLDOWN_PERIOD = 3600; // 1 hour in seconds
const lastRequestTime = 1642248600; // Unix timestamp
const currentTime = Date.now() / 1000;
const timeRemaining = COOLDOWN_PERIOD - (currentTime - lastRequestTime);

const canRequest = timeRemaining <= 0;

Integration Examples

API Integration

Use the GTX DEX API to programmatically request test tokens:
// Request test tokens via API
async function requestTestTokens() {
  try {
    // Check eligibility first
    const eligibilityResponse = await fetch(
      `https://api.gtxdex.xyz/v1/faucet/eligibility?address=${userAddress}&token=0xC004514803F58b09eee24471BC9EfF3D1087CffF`,
      {
        headers: {
          'Authorization': `Bearer ${apiKey}`
        }
      }
    );
    
    const eligibility = await eligibilityResponse.json();
    
    if (!eligibility.eligible) {
      console.log('Still in cooldown period. Next request available:', eligibility.nextRequestTime);
      return;
    }
    
    // Request tokens
    const requestResponse = await fetch('https://api.gtxdex.xyz/v1/faucet/request', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`
      },
      body: JSON.stringify({
        token: '0xC004514803F58b09eee24471BC9EfF3D1087CffF', // MUSDC
        recipient: userAddress
      })
    });
    
    const result = await requestResponse.json();
    console.log('Tokens requested:', result.transactionHash);
    console.log('Amount received:', result.amount);
  } catch (error) {
    console.error('Faucet request failed:', error);
  }
}

Automated Testing Setup

Test Environment Setup

class TestEnvironment {
  private faucet: GTXFaucet;
  private client: GTXClient;
  
  constructor() {
    this.faucet = new GTXFaucet({
      chainId: ChainId.GTX_DEVNET,
      privateKey: process.env.TEST_PRIVATE_KEY
    });
    
    this.client = new GTXClient({
      chainId: ChainId.GTX_DEVNET,
      privateKey: process.env.TEST_PRIVATE_KEY
    });
  }
  
  async setupTradingTokens() {
    const tokens = [
      { symbol: 'MUSDC', address: '0xC004514803F58b09eee24471BC9EfF3D1087CffF' },
      { symbol: 'mWETH', address: '0xbb66130EED9BD4ea584cf283d34E49E8d4d69e99' },
      { symbol: 'mWBTC', address: '0xdDbe918dcA0F0B876c2Dff6ff3db4FA0C943A293' }
    ];
    
    for (const token of tokens) {
      try {
        await this.faucet.requestTokens({
          token: token.address,
          recipient: await this.client.getAddress()
        });
        
        console.log(`✅ Received ${token.symbol} test tokens`);
        
        // Wait for cooldown between requests
        await new Promise(resolve => setTimeout(resolve, 5000));
      } catch (error) {
        console.error(`❌ Failed to get ${token.symbol}:`, error);
      }
    }
  }
  
  async verifyBalances() {
    const account = await this.client.getAccount();
    
    console.log('📊 Test token balances:');
    account.balances.forEach(balance => {
      if (parseFloat(balance.free) > 0) {
        console.log(`  ${balance.asset}: ${balance.free}`);
      }
    });
  }
}

// Usage
const testEnv = new TestEnvironment();
await testEnv.setupTradingTokens();
await testEnv.verifyBalances();

Integration Testing

class FaucetIntegrationTest {
  private faucet: GTXFaucet;
  
  constructor() {
    this.faucet = new GTXFaucet({
      chainId: ChainId.GTX_DEVNET,
      privateKey: process.env.TEST_PRIVATE_KEY
    });
  }
  
  async runTestSuite() {
    console.log('🧪 Running faucet integration tests...');
    
    // Test 1: Request tokens
    await this.testTokenRequest();
    
    // Test 2: Verify cooldown
    await this.testCooldownPeriod();
    
    // Test 3: Check balance updates
    await this.testBalanceUpdates();
    
    console.log('✅ All faucet tests completed');
  }
  
  private async testTokenRequest() {
    try {
      const result = await this.faucet.requestTokens({
        token: '0xC004514803F58b09eee24471BC9EfF3D1087CffF',
        recipient: await this.faucet.getAddress()
      });
      
      console.log('✅ Token request successful:', result.transactionHash);
    } catch (error) {
      console.error('❌ Token request failed:', error);
    }
  }
  
  private async testCooldownPeriod() {
    try {
      // This should fail due to cooldown
      await this.faucet.requestTokens({
        token: '0xC004514803F58b09eee24471BC9EfF3D1087CffF',
        recipient: await this.faucet.getAddress()
      });
      
      console.error('❌ Cooldown test failed - request should have been rejected');
    } catch (error) {
      if (error.message.includes('cooldown')) {
        console.log('✅ Cooldown protection working correctly');
      } else {
        console.error('❌ Unexpected error:', error);
      }
    }
  }
  
  private async testBalanceUpdates() {
    const balanceBefore = await this.faucet.getBalance(
      await this.faucet.getAddress(),
      '0xC004514803F58b09eee24471BC9EfF3D1087CffF'
    );
    
    // Wait for cooldown then request again
    await new Promise(resolve => setTimeout(resolve, 3600000)); // 1 hour
    
    await this.faucet.requestTokens({
      token: '0xC004514803F58b09eee24471BC9EfF3D1087CffF',
      recipient: await this.faucet.getAddress()
    });
    
    const balanceAfter = await this.faucet.getBalance(
      await this.faucet.getAddress(),
      '0xC004514803F58b09eee24471BC9EfF3D1087CffF'
    );
    
    if (balanceAfter > balanceBefore) {
      console.log('✅ Balance updated correctly');
    } else {
      console.error('❌ Balance not updated');
    }
  }
}

Development Best Practices

Test Token Management

1

Plan Token Needs

Determine which tokens and amounts you need for testing
2

Respect Cooldowns

Space out requests according to cooldown periods
3

Monitor Balances

Track both personal and faucet balances to avoid waste
4

Use Efficiently

Don’t request more tokens than needed for testing

Testing Workflows

Contract Development Workflow
  1. Deploy contracts to testnet
  2. Request test tokens for contract addresses
  3. Test token transfers and interactions
  4. Verify balance changes and events
  5. Test edge cases and error conditions
UI/UX Testing Process
  1. Request tokens for test accounts
  2. Test wallet connection flows
  3. Verify balance displays and updates
  4. Test trading and swap interfaces
  5. Validate transaction confirmations
Backend Integration
  1. Request tokens for API testing
  2. Test balance queries and updates
  3. Verify transaction monitoring
  4. Test error handling and retries
  5. Validate data synchronization

Troubleshooting

Common Issues

IssueCauseSolution
Cooldown ActiveRecent request madeWait for cooldown period to expire
Insufficient Faucet BalanceFaucet needs refillingTry different token or wait for refill
Transaction FailedNetwork congestionRetry with higher gas price
Wrong NetworkConnected to mainnetSwitch to GTX devnet

Error Handling

try {
  await faucet.requestTokens({
    token: tokenAddress,
    recipient: userAddress
  });
} catch (error) {
  if (error.message.includes('cooldown')) {
    console.log('Please wait for cooldown period');
  } else if (error.message.includes('insufficient')) {
    console.log('Faucet balance too low, try again later');
  } else if (error.message.includes('network')) {
    console.log('Check network connection and retry');
  } else {
    console.error('Unexpected error:', error);
  }
}

Network Configuration

To use the faucet, ensure your wallet is connected to GTX devnet:
// Network configuration for GTX devnet
const gtxDevnet = {
  chainId: 1802,
  chainName: 'GTX Devnet',
  nativeCurrency: {
    name: 'Ethereum',
    symbol: 'ETH',
    decimals: 18
  },
  rpcUrls: ['https://testnet-rpc.gtxdex.xyz'],
  blockExplorerUrls: ['https://testnet-explorer.gtxdex.xyz']
};

The test token faucet is essential for development and testing on GTX DEX. Use it responsibly and respect cooldown periods to ensure fair access for all developers.