elizaos-plugin-solanacloud

ElizaOS plugin that lets your agent pay for LLM inference with USDC on Solana using the x402 protocol.

No API keys. No subscriptions. Just USDC.

How it works

Agent sends prompt ──> LLM endpoint returns 402 ──> Plugin pays USDC on Solana ──> Agent gets response

1. Your agent sends a request to the LLM endpoint
2. The endpoint returns HTTP 402 with payment requirements
3. The plugin requests a pre-signed transaction from the server (the server pays gas fees)
4. Your agent signs the transaction with its Solana wallet and sends it on-chain
5. The plugin retries the original request with the X-PAYMENT-TX header
6. Your agent gets the LLM response

Each inference costs 0.0003 USDC. Your wallet only needs USDC — no SOL required.

Quick Start

1. Create an ElizaOS project

bun i -g @elizaos/cli
elizaos create my-agent --type project
cd my-agent

2. Install the plugin

bun add elizaos-plugin-solanacloud

3. Add to your character

// src/character.ts
import { type Character } from '@elizaos/core';

export const character: Character = {
  name: 'MyAgent',
  plugins: [
    '@elizaos/plugin-sql',
    '@elizaos/plugin-bootstrap',
    'elizaos-plugin-solanacloud',
  ],
  system: 'You are a helpful AI assistant.',
  bio: ['A friendly and knowledgeable assistant'],
  style: {
    all: ['Be concise and helpful'],
    chat: ['Be conversational'],
  },
};

4. Configure your wallet

Add your Solana private key to .env:

SOLANA_PRIVATE_KEY=your-base58-private-key

5. Fund your wallet

Send USDC to your agent's wallet address. You can derive it from your private key or check the logs when the agent starts.

SOL is not required — the server covers transaction fees.

6. Run

elizaos dev

Your agent is now live at http://localhost:3000.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SOLANA_PRIVATE_KEY | Yes | — | Solana wallet private key (base58 encoded) | | SOLANA_RPC_URL | No | https://api.mainnet-beta.solana.com | Solana RPC endpoint | | API_URL | No | SolanaCloud endpoint | x402 LLM endpoint URL |

Generate a new wallet

If you need a new wallet, you can generate one with:

bun -e "
const { Keypair } = require('@solana/web3.js');
const bs58 = require('bs58');
const kp = Keypair.generate();
console.log('Address:', kp.publicKey.toBase58());
console.log('Private Key:', bs58.default.encode(kp.secretKey));
"

Save the private key in your .env and send USDC to the address.

How the x402 protocol works

x402 revives HTTP status code 402 ("Payment Required") for machine-to-machine payments:

┌─────────┐         ┌─────────────┐         ┌──────────┐
│  Agent  │──POST──>│ LLM Endpoint│         │  Solana  │
│         │<──402───│             │         │          │
│         │         │             │         │          │
│         │──POST──>│/build-payment│         │          │
│         │<──tx────│ (pre-signed)│         │          │
│         │         │             │         │          │
│         │──sign + send───────────────────>│          │
│         │<──────────────confirmed─────────│          │
│         │         │             │         │          │
│         │──POST──>│ LLM Endpoint│         │          │
│         │ (X-PAYMENT-TX header) │         │          │
│         │<──200───│  (response) │         │          │
└─────────┘         └─────────────┘         └──────────┘

The server builds the transaction and pays gas. Your agent only signs with its private key and pays the USDC amount.

FAQ

Do I need an API key? No. Payment is the authentication.

Do I need SOL for gas? No. The server pays transaction fees.

How much does each request cost? 0.0003 USDC per inference call. ElizaOS makes ~2 calls per message (thought + reply), so ~0.0006 USDC per user message.

Can I use this with other ElizaOS plugins? Yes. It only registers as a model provider. All other plugins (Discord, Telegram, Twitter, etc.) work normally.

What if I also have OpenAI/Anthropic plugins? This plugin has priority: 100, so it takes precedence. Remove it from plugins to fall back to other providers.

License

MIT