sms-wallet-agent

Interact with Solana blockchain wallets through SMS messages. Text a phone number and receive wallet information instantly — no crypto knowledge required.

How It Works

SMS → Twilio → Express Webhook → Intent Parser → Wallet Service → SMS Response

Features

• balance — Get SOL balance for any wallet
• activity — View recent transactions summarized for SMS
• portfolio — SOL balance + top SPL tokens
• track — Get notified when a wallet has activity
• stop — Stop tracking a wallet

Read-only. Never requests private keys, seed phrases, or passwords. Never signs or broadcasts transactions.

Installation

npm install -g sms-wallet-agent

Or clone and install locally:

git clone <repo-url>
cd sms-wallet-agent
npm install
npm run build
npm link

Configuration

Copy the example env file and fill in your credentials:

cp .env.example .env

| Variable | Description | |---|---| | PORT | Server port (default: 3000) | | SOLANA_RPC_URL | Solana RPC endpoint | | TWILIO_ACCOUNT_SID | Twilio account SID | | TWILIO_AUTH_TOKEN | Twilio auth token | | TWILIO_PHONE_NUMBER | Your Twilio phone number |

Data is stored in ~/.config/sms-wallet-agent/:

• config.json — App configuration
• tracked-wallets.json — Phone-to-wallet tracking mappings
• state.json — Last-known wallet state for change detection

Run

sms-wallet-agent start

You should see:

✓ SMS server running on port 3000
✓ Tracking active

Twilio Setup

1. Expose your local server with ngrok:

ngrok http 3000

2. In the Twilio Console, go to your phone number settings.

3. Set the webhook URL for incoming messages:

https://YOUR_NGROK_URL/sms

Method: POST

4. Send a text to your Twilio number:

balance 8xQeWvG816bUx9EPjZmqJ9jZmqJ9jZmqJ9jZmqJ9jZmq

Commands

Text any of these to your Twilio number:

| Command | Example | Response | |---|---|---| | help | help | List of available commands | | balance | balance 8xQe... | SOL balance | | activity | activity 8xQe... | Recent activity summary + Solscan link | | portfolio | portfolio 8xQe... | SOL + top tokens | | track | track 8xQe... | Start activity notifications | | stop | stop 8xQe... | Stop tracking |

Example Conversation

You:   balance 8xQeWvG816bUx9EP...
Agent: Balance:
       2.41 SOL

You:   activity 8xQeWvG816bUx9EP...
Agent: Recent Activity:

       • SOL received
       • Swapped BONK -> SOL
       • NFT Transfer

       View:
       https://solscan.io/account/8xQe...

You:   track 8xQeWvG816bUx9EP...
Agent: Done.

       I will notify you when this wallet has activity.

[Later, automatically:]
Agent: 🚨 Wallet Activity

       Wallet:
       8xQe...EPjZ

       Event:
       NFT Sale

       Amount:
       4.2 SOL

Development

npm install
npm run dev        # Run with tsx (hot reload)
npm run build      # Compile TypeScript
npm start          # Run compiled build

Security

• Read-only wallet queries only
• No private keys, seed phrases, or passwords ever requested
• No transaction signing or broadcasting
• All tracking data stored locally on your machine

License

MIT