Fund Distribution — Multi-Chain Token & Gas Distribution Skill

Manage the complete lifecycle of funding agent wallets across 8 EVM chains with 5 stablecoins + native gas tokens. Use when the user says "distribute funds", "fund agents", "rebalance", "bridge tokens", "fan out", "check balances", "inventory", "sweep funds", or similar.

Security — ABSOLUTE RULES

1. NEVER show private keys in terminal output, bash commands, or logs
2. Load keys from AWS Secrets Manager — never hardcode or pass inline:

   # Load master wallet key from AWS SM without displaying it
   node -e "
   const { execSync } = require('child_process');
   const raw = execSync('aws secretsmanager get-secret-value --secret-id YOUR_SECRET_PATH/x402 --query SecretString --output text --region us-east-2', {encoding:'utf8'});
   const pk = JSON.parse(raw).PRIVATE_KEY;
   execSync('npx tsx kk/<script>.ts <args>', {
     stdio: 'inherit',
     env: { ...process.env, WALLET_PRIVATE_KEY: pk, PRIVATE_KEY: pk }
   });
   "

1. Scripts only print public addresses — verify before running any new script
2. User is always streaming — assume screen is visible to audience

Key Wallet References (public addresses only)

Prerequisites

• Node.js + tsx: cd scripts && npm install
• AWS CLI configured: Account <YOUR_AWS_ACCOUNT_ID>, region us-east-2
• Wallet manifest: scripts/kk/config/wallets.json (generated by generate-wallets.ts)
• Allocation file (optional): scripts/kk/config/allocation.json (generated by generate-allocation.ts)

Tooling Overview

All scripts live in scripts/kk/. Run from scripts/ directory.

Facilitator Token Support Matrix

This matrix defines which tokens the Ultravioleta Facilitator accepts for payments on each chain. Source: https://facilitator.ultravioletadao.xyz

*Squid requires SQUID_INTEGRATOR_ID env var (apply at squidrouter.typeform.com/integrator-id).

Token config source of truth: scripts/kk/lib/chains.ts — must match Facilitator.

Phase 0: Inventory Check

ALWAYS start here. Check what you have before doing anything.

cd scripts
# Uses master wallet from AWS SM:
node -e "
const { execSync } = require('child_process');
const raw = execSync('aws secretsmanager get-secret-value --secret-id YOUR_SECRET_PATH/x402 --query SecretString --output text --region us-east-2', {encoding:'utf8'});
const pk = JSON.parse(raw).PRIVATE_KEY;
execSync('npx tsx kk/check-full-inventory.ts', {
  stdio: 'inherit',
  env: { ...process.env, WALLET_PRIVATE_KEY: pk, PRIVATE_KEY: pk }
});
"

Output: Per-chain breakdown of all stablecoin balances + native gas, plus totals per token and Facilitator support matrix.

Phase 1: Generate Allocation Plan (Optional)

If distributing per a budget plan:

cd scripts
npx tsx kk/generate-allocation.ts --budget 200 --output config/allocation.json

This creates a randomized allocation of the budget across agents and chains, respecting token availability per chain.

Phase 2: Bridge USDC to Target Chains

Bridge USDC from a source chain (typically Avalanche) to all destination chains.

2a. With Allocation File

# Dry run first (ALWAYS)
npx tsx kk/bridge-from-source.ts --source avalanche --allocation config/allocation.json --dry-run

# Execute
npx tsx kk/bridge-from-source.ts --source avalanche --allocation config/allocation.json

2b. Manual (specific chains + amounts)

# Bridge $20 USDC to specific chains
npx tsx kk/bridge-from-source.ts --source avalanche --chains base,polygon --amount 20 --dry-run
npx tsx kk/bridge-from-source.ts --source avalanche --chains base,polygon --amount 20

Bridge Coverage

• deBridge DLN: Base, Ethereum, Polygon, Arbitrum, Avalanche, Optimism, Monad (7/8)
• Squid Router: Base, Ethereum, Polygon, Arbitrum, Avalanche, Optimism, Celo (7/8, needs integrator ID)
• Combined: All 8 chains covered. bridge-router.ts auto-selects the best provider.

Important Notes

• deBridge requires 2% approve buffer (execution fee varies between quote and TX)
• Monad uses deBridge chain ID 100000030 (not 143)
• Wait for bridge confirmation before proceeding (3-5 min typically, Ethereum up to 15 min)

Phase 3: Bridge Native Gas Tokens

Bridge USDC from Avalanche to native gas tokens (ETH, POL, CELO, MON) on destination chains.

# Dry run — shows quotes only
npx tsx kk/bridge-gas.ts --dry-run

# Execute all chains that need gas
npx tsx kk/bridge-gas.ts

# Specific chains only
npx tsx kk/bridge-gas.ts --chains base,monad

Gas Budget Reference (for 24 agents)

Note: Gas amounts in bridge-gas.ts:GAS_TARGETS include master wallet buffer. Adjust if budget is tight.

Phase 4: Distribute Tokens to Agent Wallets (Fan-Out)

4a. Uniform Distribution (same amount per wallet)

# Dry run first
npx tsx kk/distribute-funds.ts --chain base --tokens USDC --amount 0.20 --gas 0.0002 --dry-run

# Execute — all tokens on one chain
npx tsx kk/distribute-funds.ts --chain base --tokens USDC,EURC --amount 0.10 --gas 0.0002

# Gas only (no tokens)
npx tsx kk/distribute-funds.ts --chain ethereum --tokens USDC --amount 0 --gas 0.00015

4b. Allocation-Based Distribution (per-agent amounts)

npx tsx kk/distribute-funds.ts --chain base --allocation config/allocation.json --dry-run
npx tsx kk/distribute-funds.ts --chain base --allocation config/allocation.json

How Distribute Works

1. Disperse.app (batch, 1 TX for all): Base, Ethereum, Polygon, Arbitrum, Avalanche, Optimism
2. Sequential transfers (1 TX per wallet): Celo, Monad (no Disperse deployed)
3. For each token: Approve → Disperse/Transfer
4. For gas: DisperseEther (batch) or sendTransaction (sequential)

Recommended Distribution Order

Execute per chain, all tokens + gas in one command:

# Base: USDC + EURC + gas
npx tsx kk/distribute-funds.ts --chain base --tokens USDC,EURC --amount 0.10 --gas 0.0002

# Ethereum: USDC + EURC + AUSD + PYUSD + gas (expensive! small amounts)
npx tsx kk/distribute-funds.ts --chain ethereum --tokens USDC,EURC,AUSD,PYUSD --amount 0.10 --gas 0.00015

# Polygon: USDC + AUSD + gas
npx tsx kk/distribute-funds.ts --chain polygon --tokens USDC,AUSD --amount 0.05 --gas 0.1

# Arbitrum: USDC + USDT + AUSD + gas
npx tsx kk/distribute-funds.ts --chain arbitrum --tokens USDC,USDT,AUSD --amount 0.10 --gas 0.0002

# Avalanche: USDC + EURC + AUSD + gas
npx tsx kk/distribute-funds.ts --chain avalanche --tokens USDC,EURC,AUSD --amount 0.10 --gas 0.005

# Optimism: USDC + USDT + gas
npx tsx kk/distribute-funds.ts --chain optimism --tokens USDC,USDT --amount 0.10 --gas 0.0002

# Celo: USDC + USDT + gas (sequential — slow, ~2min)
npx tsx kk/distribute-funds.ts --chain celo --tokens USDC,USDT --amount 0.02 --gas 0.01

# Monad: USDC + AUSD + gas (sequential — slow, ~2min)
npx tsx kk/distribute-funds.ts --chain monad --tokens USDC,AUSD --amount 0.10 --gas 0.01

Phase 5: Rebalancing

When funds are unevenly distributed or need redistribution:

5a. Sweep Funds Back to Master

# Dry run — see what would be recovered
npx tsx kk/sweep-funds.ts --target YOUR_PLATFORM_WALLET --dry-run

# Sweep specific chains
npx tsx kk/sweep-funds.ts --target 0xD386... --chains monad,polygon

# Tokens only (keep gas in wallets)
npx tsx kk/sweep-funds.ts --target 0xD386... --tokens-only

5b. Bridge Between Chains

If one chain has excess and another needs more:

# Bridge $10 USDC from Avalanche to Arbitrum
npx tsx kk/bridge-from-source.ts --source avalanche --chains arbitrum --amount 10

5c. Re-distribute After Rebalancing

Run Phase 4 again with adjusted amounts.

Phase 6: Verification

After any operation, re-run the full inventory:

npx tsx kk/check-full-inventory.ts

Compare with the allocation plan. All agents should have:

• Gas tokens for ~10-20 TXs on each chain
• $0.10-0.50 of each supported stablecoin per chain

Troubleshooting

"INSUFFICIENT NATIVE" during distribute

Master wallet doesn't have enough gas for the Disperse TX itself. Either:

• Bridge more native gas (Phase 3)
• Reduce --gas amount per agent

"INSUFFICIENT [TOKEN]" during distribute

Master wallet doesn't have enough of that stablecoin. Either:

• Bridge more from source chain (Phase 2)
• Reduce --amount

deBridge quote fails

• Check if the chain is supported (Celo is NOT on deBridge)
• Ensure USDC balance on source chain is sufficient
• Public RPCs may be down — set private RPC in .env.local (e.g., AVALANCHE_RPC_URL)
• CRITICAL: .env.local must be loaded BEFORE importing chains.ts (import order matters in scripts)

Squid bridge fails

• Ensure SQUID_INTEGRATOR_ID env var is set
• Apply at https://squidrouter.typeform.com/integrator-id if needed

"transfer amount exceeds allowance" (deBridge)

deBridge execution fee varies between quote and TX. Scripts add 2% buffer on approve. If still failing, increase buffer in bridge-from-source.ts or bridge-gas.ts.

Monad/Celo sequential transfers are slow

These chains don't have Disperse.app deployed. Each transfer is 1 TX. 24 agents × 2-3 tokens = 48-72 TXs. Expect ~2-5 minutes per chain.

Shell issues on Windows

If echo, export, or other bash commands fail, use the Node.js wrapper pattern:

node -e "
const { execSync } = require('child_process');
execSync('npx tsx kk/<script>.ts <args>', {
  stdio: 'inherit',
  env: { ...process.env, WALLET_PRIVATE_KEY: '<loaded-from-aws>' }
});
"

Budget Planning Rules

• Testing bounties: $0.10 each — $5 per chain = 50 tests
• Gas: L2s are ~$0.001/TX, so 0.0002 ETH = ~500 TXs per agent
• Ethereum L1: More expensive — budget 0.00015 ETH/agent (~20 TXs)
• Reserve: Keep ~$10-20 USDC on Avalanche as reserve for emergency bridges
• Token variety: Agents need at least $0.10 of EACH supported stablecoin per chain for multi-token testing
• Grand total: $200 budget covers all 8 chains × 24 agents with 5 stablecoins

Quick Reference: Full Lifecycle

1. Inventory     →  check-full-inventory.ts
2. Plan          →  generate-allocation.ts (optional)
3. Bridge USDC   →  bridge-from-source.ts
4. Bridge Gas    →  bridge-gas.ts
5. Fan Out       →  distribute-funds.ts (per chain, per token)
6. Verify        →  check-full-inventory.ts
7. Rebalance     →  sweep-funds.ts + bridge + redistribute

Related Files