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
Token Symbol Address Decimals Amount per Request Mock USD Coin MUSDC 0xC004...CffF6 1,000 MUSDC Mock Wrapped Ethereum mWETH 0xbb66...e9918 5 mWETH Mock Wrapped Bitcoin mWBTC 0xdDbe...A2938 0.1 mWBTC Mock Chainlink LINK 0x24b1...D901E18 100 LINK Mock Pepe PEPE 0x7FB2...D14787418 1,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
Connect Wallet
Connect your wallet to the GTX devnet
Select Token
Choose which test token you want to request from the dropdown
Check Cooldown
Verify you’re not in cooldown period from previous requests
Request Tokens
Click “Request Tokens” to submit your request
Confirm Transaction
Approve the transaction in your wallet
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:
Cooldown Rules
Cooldown Status
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 ;
Real-time Status Display The interface shows your cooldown status:
✅ Ready : You can request tokens
⏳ Cooling Down : Time remaining until next request
❌ Limit Reached : Daily limit exceeded
🔄 Processing : Request currently being processed
// Status examples
{
status : "ready" , // Can request immediately
timeRemaining : 0 ,
message : "Ready to request tokens"
}
{
status : "cooldown" ,
timeRemaining : 1847 , // 30 minutes 47 seconds
message : "Next request available in 30m 47s"
}
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
Plan Token Needs
Determine which tokens and amounts you need for testing
Respect Cooldowns
Space out requests according to cooldown periods
Monitor Balances
Track both personal and faucet balances to avoid waste
Use Efficiently
Don’t request more tokens than needed for testing
Testing Workflows
Contract Development Workflow
Deploy contracts to testnet
Request test tokens for contract addresses
Test token transfers and interactions
Verify balance changes and events
Test edge cases and error conditions
UI/UX Testing Process
Request tokens for test accounts
Test wallet connection flows
Verify balance displays and updates
Test trading and swap interfaces
Validate transaction confirmations
Backend Integration
Request tokens for API testing
Test balance queries and updates
Verify transaction monitoring
Test error handling and retries
Validate data synchronization
Troubleshooting
Common Issues
Issue Cause Solution Cooldown Active Recent request made Wait for cooldown period to expire Insufficient Faucet Balance Faucet needs refilling Try different token or wait for refill Transaction Failed Network congestion Retry with higher gas price Wrong Network Connected to mainnet Switch 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.