# arbilink

Adopt this skill: https://proskills.md/skills/other/astraea-sixth-arbilink

Page: https://proskills.md/skills/other/astraea-sixth-arbilink
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 4716
upstream: https://github.com/astraea-sixth/arbilink/blob/HEAD/SKILL.md

````text
---
name: arbilink
description: "Arbitrum blockchain operations — check wallet balances, get live Uniswap V3 token prices, execute swaps, and register agent identity on Arbitrum. Use when: user asks about Arbitrum balances, token prices, DeFi swaps, or agent registration on-chain. Supports Arbitrum One (mainnet) and Arbitrum Sepolia (testnet)."
---

# ArbiLink — Arbitrum Agent Toolkit

## When to use

- User asks to check an Arbitrum wallet balance (ETH or ERC20)
- User wants a live token price from Uniswap V3 on Arbitrum (any token pair by address)
- User wants to execute a token swap on Arbitrum Sepolia (testnet) with risk analysis
- User wants to register the agent identity on-chain
- User wants to view transaction history via the dashboard

## When NOT to use

- Non-Arbitrum chains (Ethereum mainnet, Optimism, Base, etc.)
- Complex DeFi operations beyond simple swaps (LP management, lending, etc.)
- Production mainnet swaps — swap.ts is testnet-only by design

## Install

```bash
cd /path/to/arbilink
npm install
cp .env.example .env
# Edit .env and add your Arbitrum Sepolia private key (for swap + register)
```

## Commands

### 1. Check balance

```bash
# ETH balance (default address, Sepolia)
npx tsx scripts/balance.ts

# ETH balance for a specific address on Arbitrum One
npx tsx scripts/balance.ts 0x1234...abcd --network one

# ERC20 token balance
npx tsx scripts/balance.ts --token 0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d --network sepolia
```

### 2. Get token price

```bash
# Any token pair by contract address (auto-detects fee tier)
npx tsx scripts/price.ts --tokenIn 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 --tokenOut 0xaf88d065e77c8cC2239327C5EDb3A432268e5831

# With explicit fee tier and amount for price impact
npx tsx scripts/price.ts --tokenIn 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 --tokenOut 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 --fee 500 --amount 10

# On Arbitrum Sepolia
npx tsx scripts/price.ts --tokenIn 0x... --tokenOut 0x... --network sepolia
```

### 3. Execute swap (testnet only)

```bash
# Swap on Arbitrum Sepolia (--testnet bypasses slippage for low-liquidity testnet pools)
npx tsx scripts/swap.ts --amount 0.001 --testnet

# Dry run (estimate only, no transaction)
npx tsx scripts/swap.ts --amount 0.01 --dry-run

# Custom tokens and slippage
npx tsx scripts/swap.ts --amount 0.001 --tokenIn WETH --tokenOut USDC --slippage 2 --testnet

# Override risk check and amount cap
npx tsx scripts/swap.ts --amount 5 --force --confirm-large --max-amount 10 --testnet
```

> **Note:** `--testnet` sets `amountOutMinimum = 0` since Sepolia pools have near-zero liquidity. On mainnet, omit `--testnet` for full slippage protection.

### 4. Register agent identity (ERC-8004)

```bash
# Register with default agent profile
npx tsx scripts/register.ts

# Custom name and description
npx tsx scripts/register.ts --name "My Agent" --description "An AI agent on Arbitrum"

# Check if wallet is registered (no private key needed)
npx tsx scripts/register.ts --check
```

### 5. Transaction dashboard

```bash
# Start the dashboard at http://localhost:3099
npx tsx scripts/dashboard.ts
```

## Transaction Logging

All swaps and registrations are logged to `logs/transactions.jsonl` (JSONL format, one entry per line). The dashboard reads this file for display.

## Network Configuration

| Network          | Usage                              | RPC                                        |
|------------------|-------------------------------------|---------------------------------------------|
| Arbitrum One     | Swaps, price lookups (mainnet)     | https://arb1.arbitrum.io/rpc                |
| Arbitrum Sepolia | Swaps, registration, testing       | https://sepolia-rollup.arbitrum.io/rpc      |

## Verified Transactions

- **Registration** (Arbitrum Sepolia): [`0xacca222f...`](https://sepolia.arbiscan.io/tx/0xacca222f9748479b7e05fb1491f542b1ffe20d12805f3f6cc5be09e4bf08e17e)
- **Swap** (Arbitrum One mainnet): [`0xc971bcc6...`](https://arbiscan.io/tx/0xc971bcc6cf32117e83d756939088bd4d93c89a1fd16c716d706122c8e2a2b02a)

## Security

- Private key is loaded from `.env` (gitignored) — never committed to the repo
- swap.ts and register.ts require `PRIVATE_KEY` in `.env` — they exit with an error if missing
- swap.ts runs a GoPlus + DEXScreener risk scorecard before executing (blocks dangerous tokens unless --force)
- swap.ts enforces max slippage (50%), amount caps, and balance checks
- Use a **testnet-only** key — never fund it with real assets
- balance.ts and price.ts are read-only and require no private key

## Contract Reference

See [references/contracts.md](references/contracts.md) for all contract addresses and ABIs.
````

## File: README.md
upstream: https://github.com/astraea-sixth/arbilink/blob/HEAD/README.md

````text
# ArbiLink

**AI agents manage on-chain assets — but they can't detect honeypots, rugged pools, or sandwich attacks.** ArbiLink is an [OpenClaw](https://github.com/openclaw/openclaw) skill that gives any AI agent a pre-swap risk scorecard, live Uniswap V3 prices, safe swap execution, and on-chain identity registration — all on Arbitrum.

Built for the [Arbitrum Foundation Agentic Bounty](https://www.arbitrum.foundation/).

---

## Install (OpenClaw)

Send this to your OpenClaw agent:

> "Please follow the SKILL.md at https://raw.githubusercontent.com/Astraea-Sixth/arbilink/main/SKILL.md and set up ArbiLink on this machine."

Your agent will clone the repo, install dependencies, and confirm when ready.

### Manual install

```bash
git clone https://github.com/Astraea-Sixth/arbilink && cd arbilink
npm install
cp .env.example .env   # add your private key for swap/register
```

---

## Architecture

```
┌─────────────────┐
│  OpenClaw Agent  │
└────────┬────────┘
         │  natural language → script execution
         ▼
┌─────────────────┐
│  ArbiLink Skill  │
│                  │
│  balance.ts ─────┼──▶  Arbitrum RPC (ETH/ERC20 balances)
│  portfolio.ts ───┼──▶  Arbitrum RPC + QuoterV2 (all balances + USD)
│  price.ts ───────┼──▶  Uniswap V3 QuoterV2 (live prices)
│  swap.ts ────────┼──▶  Uniswap V3 SwapRouter (execution)
│      │           │      ├─▶ GoPlus Security API (honeypot/tax detection)
│      │           │      └─▶ DEXScreener API (liquidity analysis)
│  watch.ts ───────┼──▶  GoPlus API (continuous risk monitoring)
│  gas.ts ─────────┼──▶  Arbitrum RPC (gas price + swap cost estimate)
│  history.ts ─────┼──▶  Arbiscan V2 API (transaction history)
│  register.ts ────┼──▶  Arbitrum Identity Registry (ERC-8004)
│  dashboard.ts ───┼──▶  localhost:3099 (transaction history UI)
└─────────────────┘
```

---

## Real Output

### Check balance

```
$ npx tsx scripts/balance.ts --network one
Address: 0xa6b18B26717bBd10A3Ae828052C8CA35Ef5EcB8b | Network: Arbitrum One | ETH: 0.00149
```

### Live price (any token pair)

```
$ npx tsx scripts/price.ts --tokenIn 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 \
    --tokenOut 0xaf88d065e77c8cC2239327C5EDb3A432268e5831
WETH/USDC on Arbitrum One
  Pool: 0xC6962004f452bE9203591991D15f6b388e09E8D0
  Fee tier: 0.05%
  Price: 1 WETH = 2,041.97 USDC
```

### Safe swap (dry run)

```
$ npx tsx scripts/swap.ts --amount 0.001 --network one --dry-run
Estimated output: 2.041987 USDC

--- DRY RUN ---
Swap: 0.001 WETH -> USDC
Network: Arbitrum One
Amount in: 0.001 WETH
Min output: 2.021568 USDC
Slippage: 1%
Fee tier: 0.05%
```

### Honeypot blocked by risk scorecard

```
$ npx tsx scripts/swap.ts --amount 0.1 --tokenOut 0xDEAD...SCAM --network one --dry-run

--- Risk Scorecard: SCAM ---
Score: 2/10 🔴 DANGER

Passed:
  ✅ Listed on DEX

Warnings:
  ⚠️  HONEYPOT — cannot sell after buying
  ⚠️  Sell tax: 99.0%
  ⚠️  Contract is not open source
  ⚠️  LP not locked
  ⚠️  Creator holds 45.2%
  ⚠️  Low holder count: 47
  ⚠️  Low DEX liquidity: $8,400

Risk score too low (2/10). Use --force to override.
```

### Agent registration (ERC-8004)

```
$ npx tsx scripts/register.ts --name "Astraea" --description "OpenClaw AI agent"
Registering agent on Arbitrum Sepolia...
Tx submitted: 0xacca222f9748479b7e05fb1491f542b1ffe20d12805f3f6cc5be09e4bf08e17e

--- Registration Complete ---
Tx hash: 0xacca222f...
Gas used: 338830
Block: 255910945
Agent ID (token): 50
```

### Portfolio overview

```
$ npx tsx scripts/portfolio.ts --network one

Portfolio for 0xa6b1...cB8b on Arbitrum One
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Token              Balance         Price         Value
  ──────────────────────────────────────────────────────
  ETH               0.001494      $2,042.71        $3.05
  USDC                  2.04         $1.00          $2.04
  ──────────────────────────────────────────────────────
  TOTAL                                            $5.09
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Multi-token price table

```
$ npx tsx scripts/price.ts --tokens WETH,ARB

Token Prices on Arbitrum One (vs USDC)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Token              Price (USD)         Fee
  ──────────────────────────────────────────
  WETH               $2,042.8338       0.05%
  ARB                    $0.0909       0.05%
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Gas price check

```
$ npx tsx scripts/gas.ts --network one

Gas Report — Arbitrum One
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Gas price:    0.0200 gwei
  Swap cost:    0.000003 ETH (est. 150000 gas)
  ETH price:    $2,041.69
  Swap cost:    $0.0061 USD

  Recommendation: LOW — great time to swap
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Token risk scan

```
$ npx tsx scripts/scan.ts 0x912CE59144191C1204E64559FE8253a0e49E6548

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 TOKEN SCAN — ARB
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Name:         Arbitrum (ARB)
 Address:      0x912CE59144191C1204E64559FE8253a0e49E6548
 Network:      Arbitrum One
 Total supply: 10,000,000,000
 Price:        $0.091368
 Liquidity:    $221,823
 24h volume:   $14,200,000

 Risk Score:   9/10  ✅ SAFE

 Passed:
   ✅ Not a honeypot
   ✅ Buy tax: 0.0%
   ✅ Sell tax: 0.0%
   ✅ Contract is verified / open source
   ✅ Creator holds 0.0%
   ✅ No other potential risks flagged
   ✅ Holder count: 1,205,000
   ✅ DEX liquidity: $221,823

 Verdict:      ✅ SAFE — Token passes most security checks.
 Explorer:     https://arbiscan.io/token/0x912CE...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## On-Chain Proof

| Action | TX Hash | Network | Link |
|---|---|---|---|
| Agent Registration | `0xacca222f...e17e` | Arbitrum Sepolia | [View on Arbiscan](https://sepolia.arbiscan.io/tx/0xacca222f9748479b7e05fb1491f542b1ffe20d12805f3f6cc5be09e4bf08e17e) |
| WETH → USDC Swap | `0xc971bcc6...b02a` | Arbitrum One | [View on Arbiscan](https://arbiscan.io/tx/0xc971bcc6cf32117e83d756939088bd4d93c89a1fd16c716d706122c8e2a2b02a) |

---

## Scripts

| Script | Purpose | Network | Requires Key |
|---|---|---|---|
| `balance.ts` | ETH / ERC20 balance check | Both | No |
| `portfolio.ts` | All token balances + USD values | Both | No |
| `price.ts` | Live Uniswap V3 price (single pair or `--tokens` table) | Both | No |
| `gas.ts` | Current gas price + swap cost estimate in USD | Both | No |
| `scan.ts` | Standalone token risk scanner (GoPlus + DEXScreener) | Both | No |
| `swap.ts` | Token swap with risk scorecard + security checks | Both | Yes |
| `watch.ts` | Continuous token risk monitoring with alerts | Both | No |
| `history.ts` | Transaction history from Arbiscan V2 API | Both | Arbiscan key |
| `register.ts` | On-chain agent identity (ERC-8004) | Sepolia | Yes |
| `dashboard.ts` | Transaction history web UI (localhost:3099) | N/A | No |

### Key flags (swap.ts)

| Flag | Purpose |
|---|---|
| `--network one\|sepolia` | Target network (default: sepolia) |
| `--fee 500\|3000\|10000` | Uniswap fee tier |
| `--slippage N` | Max slippage % (default: 1, cap: 50) |
| `--dry-run` | Estimate only, no execution |
| `--testnet` | Zero slippage protection (for broken testnet pools) |
| `--force` | Override risk scorecard blocks |
| `--max-amount N` | Max swap size in token units (default: 1) |
| `--confirm-large` | Override max amount cap |

---

## Config

All addresses, RPCs, and contract references live in [`config/networks.json`](config/networks.json) — zero hardcoded values in scripts.

```
config/
  networks.json      # Addresses, RPCs, tokens for each network
  loadConfig.ts      # Typed config loader
```

## Security

- Private key loaded from `.env` (gitignored) — never in the repo
- Pre-swap risk scorecard via GoPlus + DEXScreener (blocks score < 5 unless `--force`)
- Slippage enforcement with BigInt math (`amountOutMinimum = quote * (1 - slippage/100)`)
- Balance + gas pre-check with clear error
````
