usdg-auto-claim

# USDG Auto-Claim Tool

Autonomous agent tool for claiming USDG tokens on Solana with error handling, retry logic, circuit breaker, and gas optimization.

## Features

- **USDG Token Claim Logic** — Detect and claim USDG (Global Dollar by Paxos) tokens in a Solana wallet
- **Auto-Sweep** — Automatically sweep tokens to a treasury when balance exceeds a configurable threshold
- **Error Handling** — Retry logic with exponential backoff and jitter for failed claims
- **Circuit Breaker** — Prevents cascading failures with configurable failure/success thresholds
- **Gas Optimization** — Dynamic priority fees, compute unit optimization, and transaction simulation
- **Batch Support** — Sweep to multiple treasuries in a single operation
- **Claim Eligibility Checks** — Verify balance, threshold, and SOL availability before sweeping
- **Continuous Monitoring** — Poll wallet and auto-sweep on configurable intervals
- **Agent Wallet Integration** — Integration points for autonomous agent wallet systems
- **Devnet & Mainnet** — Supports both Solana devnet and mainnet

## Requirements

- Python 3.10+
- `solana` — Solana Python SDK
- `solders` — Solana data structures
- `spl-token` — SPL Token program bindings (optional, for SPL transfers)

```bash
pip install solana solders spl-token
```

## Usage

### Check Claimable Balance

```bash
python usdg_auto_claim.py --check \
  --wallet <WALLET_PUBKEY> \
  --network mainnet
```

### Execute a Single Sweep

```bash
python usdg_auto_claim.py --sweep \
  --wallet <WALLET_PUBKEY> \
  --treasury <TREASURY_PUBKEY> \
  --keypair /path/to/keypair.json \
  --network mainnet \
  --threshold 1.0
```

### Monitor and Auto-Sweep

```bash
python usdg_auto_claim.py --monitor \
  --wallet <WALLET_PUBKEY> \
  --treasury <TREASURY_PUBKEY> \
  --keypair /path/to/keypair.json \
  --network mainnet \
  --threshold 1.0 \
  --interval 30
```

### CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `--check` | Check claimable balance and exit | — |
| `--sweep` | Execute a single sweep and exit | — |
| `--monitor` | Continuously monitor and auto-sweep | — |
| `--wallet` | Wallet public key (required) | — |
| `--treasury` | Treasury public key | — |
| `--keypair` | Path to keypair JSON file | — |
| `--network` | `devnet` or `mainnet` | `devnet` |
| `--rpc-url` | Custom RPC endpoint | — |
| `--threshold` | Min USDG to trigger sweep | `1.0` |
| `--sweep-pct` | Percentage of balance to sweep | `100` |
| `--interval` | Poll interval in seconds | `30` |
| `--token-mint` | Override token mint address | — |
| `--no-simulate` | Skip transaction simulation | `false` |
| `-v, --verbose` | Enable debug logging | `false` |

## License

MIT