Parachute

A Node.js web scraping utility for fetching token holder data from the Voyager API (Starknet blockchain explorer) and performing airdrops.

Features

• Token Holder Fetching: Retrieve paginated holder information for any ERC-20 token on Starknet
• Configurable Speed: Choose parallelization level (5-50 concurrent requests)
• Airdrop Tool: Distribute tokens to holders
• Interactive CLI: User-friendly menu-driven interface

Installation

Prerequisites

• Node.js (v14 or higher)
• npm

Setup

1. Clone the repository:

git clone https://github.com/Portablelle/Parachute.git
cd Parachute

2. Install dependencies:

npm install

This will install:

• playwright - Browser automation for web scraping
• starknet - Starknet blockchain interaction
• dotenv - Environment variable management

3. Install Playwright browsers:

npx playwright install chromium

4. Configure environment variables:

cp .env.example .env

Then edit .env and fill in your configuration:

# Starknet Wallet Configuration (required for airdrops)
STARKNET_ADDRESS=0x...           # Your deployed wallet address
STARKNET_PRIVATE_KEY=0x...       # Your wallet private key (keep secret!)
STARKNET_RPC_URL=https://...     # RPC endpoint (mainnet or testnet)

# Voyager API Configuration (optional)
VOYAGER_API_URL=https://voyager.online/api  # Default value

Important notes for airdrops:

• Environment variables are only required for the airdrop feature. Token holder fetching works without configuration.
• Your wallet must be already deployed on Starknet (not just created)
• Your wallet must have sufficient STRK tokens to cover transaction fees
• Your wallet must have the total amount of tokens you plan to airdrop (e.g., if airdropping 100 tokens to 1000 holders, you need at least 100,000 tokens)

Usage

Start the Interactive Toolbox

npm start

This launches the main menu with the following options:

═══════════════════════════════════════
         PARACHUTE TOOLBOX
═══════════════════════════════════════
1. Fetch token holders
2. Airdrop tokens to holders
0. Exit
═══════════════════════════════════════

Option 1: Fetch Token Holders

1. Select option 1 from the menu
2. Enter the token contract address (e.g., 0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7)
3. Choose parallelization speed:
   • 1 - Slow (5 parallel requests)
   • 2 - Medium (10 parallel requests)
   • 3 - Fast (20 parallel requests)
   • 4 - Very Fast (50 parallel requests)

The tool will:

• Fetch all token holders from Voyager API in batches
• Display progress in real-time
• Save results to holders/<token_prefix>_<timestamp>.json

Example output:

Fetching all holders from Voyager API (10 parallel requests)...
Page 1: Retrieved 100 holders
Fetching pages 2 to 11...
Retrieved 1000 holders (Total: 1100)
...
Data retrieval complete! Total holders: 5432
Data saved to holders/0x049_1738195234567.json

Option 2: Airdrop Tokens

1. Select option 2 from the menu
2. Follow the prompts to configure and execute the airdrop

Output Format

Holder data is saved to the holders/ directory in JSON format:

{
  "items": [
    {
      "address": "0x...",
      "balance": "1000000000000000000",
      "timestamp": 1234567890,
      ...
    }
  ],
  "total": 5432
}

Filename format: <first_5_chars_of_address>_<unix_timestamp>.json

Configuration

Environment variables are configured in the .env file (created from .env.example during installation). See the Installation section for details.

API Details

• Endpoint: https://voyager.online/api/token/{tokenAddress}/holders
• Parameters:
  • ps=100 - Items per page
  • p={pageNum} - Page number
  • type=erc20 - Token type

Technical Details

• Browser: Headless Chromium via Playwright
• User Agent: Chrome 140 on macOS
• Wait Time: 2-second delay after page load for data stability
• Context Isolation: Each page request uses a new browser context
• Batch Processing: Parallel requests until all pages return empty

Troubleshooting

No data retrieved

• Verify the token address is correct
• Check if the token exists on Starknet
• Ensure internet connectivity

Rate limiting

• Use slower parallelization speed (option 1 or 2)
• Add delays between batches if needed

Playwright errors

npx playwright install chromium

License

ISC