Phantom OpenClaw Plugin

⚠️ PREVIEW DISCLAIMER

This OpenClaw plugin is currently in preview and may break or change at any time without notice.

Always use a separate Phantom account specifically for testing with AI agents. These accounts should not contain significant assets.

Phantom makes no guarantees whatsoever around anything your agent may do using this plugin. Use at your own risk.

Direct integration with Phantom wallet for OpenClaw agents. This plugin wraps the Phantom MCP Server to provide seamless wallet operations including address retrieval, message signing, transaction signing, token transfers, and token swaps.

Overview

The Phantom OpenClaw Plugin provides native integration with Phantom wallet functionality. Instead of being a generic MCP bridge, it directly integrates the Phantom MCP Server tools as OpenClaw tools, providing a seamless experience for AI agents.

Quick Start

Get up and running in under 5 minutes:

Installation Checklist

• [ ] Step 1: Get your App ID from phantom.com/portal

  • Sign in with Gmail or Apple
  • Click "Create App"
  • Go to Dashboard → View App → Redirect URLs
  • Add http://localhost:8080/callback as a redirect URL
  • Navigate to "Phantom Connect" tab
  • Copy your App ID

• [ ] Step 2: Install the plugin

  openclaw plugins install @phantom/openclaw-plugin

• [ ] Step 3: Configure in ~/.openclaw/openclaw.json

  {
    "plugins": {
      "enabled": true,
      "entries": {
        "phantom-openclaw-plugin": {
          "enabled": true,
          "config": {
            "PHANTOM_APP_ID": "your_app_id_from_portal"
          }
        }
      }
    }
  }

• [ ] Step 4: Restart OpenClaw

• [ ] Step 5: Test with your agent

  Ask: "What are my Phantom wallet addresses?"

⚠️ Important: Use the same email address for both the Phantom Portal and OpenClaw authentication!

See Prerequisites below for detailed setup instructions.

Features

• Direct Integration: Built on top of @phantom/mcp-server for reliable wallet operations
• Automatic Authentication: Handles OAuth flow and session management automatically
• Type-Safe: Full TypeScript support with proper type definitions
• Simple Setup: Minimal configuration - just enable the plugin and use

Prerequisites

Before using this plugin, you must obtain an App ID from the Phantom Portal:

1. Visit the Phantom Portal: Go to phantom.com/portal
2. Sign in: Use your Gmail or Apple account to sign in
3. Create an App: Click "Create App" and fill in the required details
4. Configure Redirect URL:
   • Navigate to Dashboard → View App → Redirect URLs
   • Add http://localhost:8080/callback as a redirect URL
   • This allows the OAuth callback to work correctly
5. Get Your App ID: Navigate to the "Phantom Connect" tab to find your App ID
   • Your app is automatically approved for development use
   • Copy the App ID for the configuration below

Important: The email you use to sign in to the Phantom Portal must match the email you use when authenticating with the plugin. If these don't match, authentication will fail.

Installation

openclaw plugins install @phantom/openclaw-plugin

Configuration

Configure the plugin in your OpenClaw configuration file (~/.openclaw/openclaw.json):

{
  "plugins": {
    "enabled": true,
    "entries": {
      "phantom-openclaw-plugin": {
        "enabled": true,
        "config": {
          "PHANTOM_APP_ID": "your_app_id_from_portal"
        }
      }
    }
  }
}

Configuration Options

• PHANTOM_APP_ID (required): Your App ID from the Phantom Portal
• PHANTOM_CLIENT_SECRET (optional): Client secret for confidential clients
• PHANTOM_CALLBACK_PORT (optional): OAuth callback port (default: 8080)
• PHANTOM_MCP_DEBUG (optional): Enable debug logging (set to "1")

Note: Most users only need to provide PHANTOM_APP_ID. The other options are for advanced use cases.

Troubleshooting: DCR 404 During Startup

If startup fails with Failed to register OAuth client and status code 404, OpenClaw likely did not provide a valid PHANTOM_APP_ID to the plugin.

Verify your config is nested exactly at:

plugins.entries["phantom-openclaw-plugin"].config.PHANTOM_APP_ID

PHANTOM_APP_ID values are issued from phantom.com/portal.

Available Tools

The plugin exposes the following tools from the Phantom MCP Server:

get_wallet_addresses

Retrieve wallet addresses for all supported blockchain chains.

Parameters:

• derivationIndex (number, optional): Derivation index for the wallet (default: 0)

Example:

{
  "derivationIndex": 0
}

sign_message

Sign an arbitrary message with the Phantom wallet.

Parameters:

• message (string, required): The message to sign
• networkId (string, required): Network identifier (e.g., "solana:mainnet", "eip155:1")
• derivationIndex (number, optional): Derivation index for the wallet (default: 0)

Example:

{
  "message": "Hello, Phantom!",
  "networkId": "solana:mainnet",
  "derivationIndex": 0
}

sign_transaction

Sign a blockchain transaction.

Parameters:

• transaction (string, required): The transaction to sign (format depends on chain: base64url for Solana, RLP-encoded hex for Ethereum)
• networkId (string, required): Network identifier (e.g., "solana:mainnet", "eip155:1" for Ethereum mainnet)
• derivationIndex (number, optional): Derivation index for the wallet (default: 0)
• account (string, optional): Specific account address to use for simulation/signing

Example:

{
  "transaction": "base64url-encoded-transaction-data",
  "networkId": "solana:mainnet",
  "derivationIndex": 0
}

transfer_tokens

Transfer SOL or SPL tokens on Solana. Builds, signs, and sends the transaction immediately.

Parameters:

• networkId (string, required): Solana network identifier (e.g., "solana:mainnet", "solana:devnet")
• to (string, required): Recipient Solana address
• amount (string, required): Transfer amount (e.g., "0.1" or "1000000")
• amountUnit (string, optional): Unit type - "ui" for human-readable (SOL/token units) or "base" for atomic units (lamports). Default: "ui"
• tokenMint (string, optional): SPL token mint address. Omit for SOL transfers
• decimals (number, optional): Token decimals (optional for SPL tokens)
• derivationIndex (number, optional): Derivation index for the wallet (default: 0)
• createAssociatedTokenAccount (boolean, optional): Create destination ATA if missing (default: true)

Example (SOL Transfer):

{
  "networkId": "solana:mainnet",
  "to": "H8FpYTgx4Uy9aF9Nk9fCTqKKFLYQ9KfC6UJhMkMDzCBh",
  "amount": "0.1",
  "amountUnit": "ui"
}

Example (SPL Token Transfer):

{
  "networkId": "solana:devnet",
  "to": "H8FpYTgx4Uy9aF9Nk9fCTqKKFLYQ9KfC6UJhMkMDzCBh",
  "tokenMint": "So11111111111111111111111111111111111111112",
  "amount": "1.5",
  "amountUnit": "ui"
}

⚠️ Warning: This tool submits transactions immediately and irreversibly.

buy_token

Fetch a Solana swap quote from Phantom's quotes API. Optionally execute the swap immediately.

Parameters:

• networkId (string, optional): Solana network identifier (default: "solana:mainnet")
• sellTokenIsNative (boolean, optional): Set true to sell native SOL (default: true if sellTokenMint not provided)
• sellTokenMint (string, optional): Mint address of the token to sell (omit if selling native SOL)
• buyTokenIsNative (boolean, optional): Set true to buy native SOL (default: false)
• buyTokenMint (string, optional): Mint address of the token to buy (omit if buying native SOL)
• amount (string, required): Sell amount (e.g., "0.5" or "500000000")
• amountUnit (string, optional): Unit type - "ui" for token units or "base" for atomic units. Default: "base"
• slippageTolerance (number, optional): Slippage tolerance in percent (0-100)
• execute (boolean, optional): If true, signs and sends the transaction immediately. Default: false
• derivationIndex (number, optional): Derivation index for the wallet (default: 0)

Example:

{
  "networkId": "solana:mainnet",
  "sellTokenIsNative": true,
  "buyTokenMint": "So11111111111111111111111111111111111111112",
  "amount": "0.5",
  "amountUnit": "ui",
  "slippageTolerance": 1,
  "execute": true
}

⚠️ Warning: When execute: true, this tool submits transactions immediately and irreversibly.

Network IDs Reference

Network identifiers follow the CAIP-2/CAIP-10 format. Here are the supported networks:

Solana

• Mainnet: solana:mainnet
• Devnet: solana:devnet
• Testnet: solana:testnet

Ethereum / EVM Chains

• Ethereum Mainnet: eip155:1
• Ethereum Sepolia: eip155:11155111
• Polygon Mainnet: eip155:137
• Polygon Amoy: eip155:80002
• Base Mainnet: eip155:8453
• Base Sepolia: eip155:84532
• Arbitrum One: eip155:42161
• Arbitrum Sepolia: eip155:421614

Bitcoin

• Mainnet: bip122:000000000019d6689c085ae165831e93

Sui

• Mainnet: sui:mainnet
• Testnet: sui:testnet

Authentication

On first use, the plugin will automatically initiate the Phantom OAuth flow:

1. A browser window will open to https://connect.phantom.app
2. Sign in with your Google or Apple account
   • Important: Use the same email you used to sign in to the Phantom Portal
3. Authorize the application
4. The session will be saved for future use

Sessions are stored securely in ~/.phantom-mcp/session.json with restricted permissions and persist across restarts. The plugin uses stamper keypair authentication which doesn't expire.

Usage Examples

Check Wallet Addresses

User: What are my wallet addresses?
Agent: Let me check your Phantom wallet addresses.
[Calls get_wallet_addresses]

Sign a Message

User: Sign this message: "Verify ownership of my wallet"
Agent: I'll sign that message for you using your Phantom wallet.
[Calls sign_message with the message]

Sign a Transaction

User: Sign this Solana transaction: [transaction data]
Agent: I'll sign that transaction with your Phantom wallet.
[Calls sign_transaction with the transaction data]

Architecture

phantom-openclaw-plugin/
├── src/
│   ├── index.ts              # Plugin entry point
│   ├── session.ts            # Session management wrapper
│   ├── client/
│   │   └── types.ts          # OpenClaw API types
│   └── tools/
│       └── register-tools.ts # Tool registration logic
├── skills/
│   └── phantom-wallet/       # Wallet operations skill
└── openclaw.plugin.json      # Plugin manifest

Development

For contributors or those testing unreleased versions.

Prerequisites

• Node.js 18+
• yarn
• Phantom wallet account for testing
• App ID from Phantom Portal

Local Installation

1. Clone and build the plugin:

   # From the phantom-connect-sdk repository root
   yarn install
   yarn workspace @phantom/mcp-server build
   yarn workspace @phantom/openclaw-plugin build

2. Install locally into OpenClaw:

   openclaw plugins install -l ./packages/phantom-openclaw-plugin

3. Configure in ~/.openclaw/openclaw.json:

   {
     "plugins": {
       "enabled": true,
       "entries": {
         "phantom-openclaw-plugin": {
           "enabled": true,
           "config": {
             "PHANTOM_APP_ID": "your_app_id_from_portal"
           }
         }
       }
     }
   }

4. Verify installation:

   openclaw plugins list

5. Test with an agent:

   openclaw chat
   > What are my Phantom wallet addresses?

Build Commands

# Build the plugin
yarn build

# Development mode with watch
yarn dev

# Type checking
yarn check-types

# Linting
yarn lint

# Format code
yarn prettier

Troubleshooting

Plugin Not Loading

• Verify the plugin is enabled in openclaw.json
• Check that the build completed successfully (dist/ directory exists)
• Ensure both the plugin and @phantom/mcp-server are built

Authentication Fails

• Check your internet connection
• Ensure you have a Phantom wallet account
• Try clearing the session cache: rm -rf ~/.phantom-mcp/session.json
• Check the console logs for specific error messages

Tool Execution Errors

• Ensure you're authenticated (the plugin will prompt if not)
• Verify the tool parameters match the expected schema
• Check that the Phantom wallet supports the requested operation

Related Projects

• @phantom/mcp-server - The underlying MCP server providing wallet functionality
• Phantom Wallet - The Phantom wallet application

Contributing

Contributions are welcome! Please ensure:

• TypeScript types are properly defined
• Code follows the existing style (run yarn prettier)
• All builds pass (yarn build)
• Type checking passes (yarn check-types)

License

MIT

Support

For issues or questions:

• GitHub Issues: https://github.com/phantom/phantom-connect-sdk/issues
• Phantom Support: https://help.phantom.app