Skip to main content

Overview

Beacon Cloud is a hosted service that lets you generate AGENTS.md files without managing API keys or infrastructure. Instead of subscribing to AI provider APIs, you pay $0.09 USDC per generation using cryptocurrency on Base or Solana networks.

How It Works

Beacon Cloud implements the x402 payment protocol for HTTP payment-required flows:
1

Make a generation request

Call Beacon with --provider beacon-ai-cloud. No API key needed.
beacon generate ./my-project --provider beacon-ai-cloud
2

Receive payment details

Beacon Cloud returns 402 Payment Required with wallet addresses and a unique run ID.
💰 Payment required to proceed.

Please send 0.09 USDC to one of these addresses:
  - Base:   0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
  - Solana: 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
3

Send USDC payment

Transfer USDC to the provided address using your wallet (MetaMask, Phantom, etc.).
4

Submit transaction hash

Paste the transaction hash when prompted. Beacon verifies payment on-chain.
Which chain did you pay on? (base/solana)
> base

Please paste the transaction hash:
> 0x1234abcd...

🔍 Verifying payment...
5

Receive generated AGENTS.md

Once verified, Beacon Cloud processes your request and returns the generated file.
✅ Done! AGENTS.md written to: AGENTS.md

Payment Flow Architecture

The payment verification logic is in src/inferrer.rs:154-240 and src/verifier.rs:

Supported Chains

Beacon Cloud accepts USDC payments on two networks:

Base

Network: Base (Ethereum L2)USDC Contract: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913Best for: Lower gas fees, Ethereum ecosystem usersAvg. confirmation time: ~2 seconds

Solana

Network: Solana MainnetUSDC Mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1vBest for: Fastest transactions, lowest feesAvg. confirmation time: Less than 1 second

Payment Verification

Beacon Cloud verifies payments on-chain to prevent fraud:

Base Verification

From src/verifier.rs:23-52:
async fn verify_base(
    txn_hash: &str,
    expected_amount: f64,
    expected_address: &str,
) -> Result<bool> {
    let rpc_url = std::env::var("BASE_RPC_URL")
        .unwrap_or_else(|_| "https://mainnet.base.org".to_string());
    let provider = Provider::<Http>::try_from(rpc_url)?;
    let hash = H256::from_str(txn_hash)?;
    let receipt = provider.get_transaction_receipt(hash).await?
        .context("Transaction receipt not found")?;
    
    // Check transaction succeeded
    if receipt.status != Some(1.into()) {
        return Ok(false);
    }
    
    // Verify USDC transfer to correct address
    let usdc_addr = Address::from_str(BASE_USDC)?;
    let receiver_addr = Address::from_str(expected_address)?;
    let transfer_topic = H256::from_str(
        "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
    )?; // Transfer(address,address,uint256)
    
    for log in receipt.logs {
        if log.address == usdc_addr && log.topics[0] == transfer_topic {
            let to = Address::from_slice(&log.topics[2][12..]);
            if to == receiver_addr {
                let value = U256::from_big_endian(&log.data);
                let amount_f64 = value.as_u128() as f64 / 1_000_000.0; // USDC has 6 decimals
                if (amount_f64 - expected_amount).abs() < 0.001 {
                    return Ok(true);
                }
            }
        }
    }
    Ok(false)
}
Verification steps:
  1. Fetch transaction receipt from Base RPC
  2. Check transaction status is successful
  3. Parse ERC-20 Transfer event logs
  4. Verify recipient address matches
  5. Verify amount matches expected payment (±0.001 USDC tolerance)

Solana Verification

From src/verifier.rs:54-94:
async fn verify_solana(
    txn_hash: &str,
    expected_amount: f64,
    expected_address: &str,
) -> Result<bool> {
    let rpc_url = std::env::var("SOLANA_RPC_URL")
        .unwrap_or_else(|_| "https://api.mainnet-beta.solana.com".to_string());
    let client = reqwest::Client::new();
    let resp = client.post(rpc_url)
        .json(&json!({
            "jsonrpc": "2.0",
            "id": 1,
            "method": "getTransaction",
            "params": [
                txn_hash,
                { "encoding": "json", "maxSupportedTransactionVersion": 0 }
            ]
        }))
        .send().await?.json::<Value>().await?;
    
    let meta = &resp["result"]["meta"];
    let pre = meta["preTokenBalances"].as_array()?;
    let post = meta["postTokenBalances"].as_array()?;
    
    // Find USDC balance change for recipient
    let mut pre_val = 0.0;
    for b in pre {
        if b["mint"] == SOLANA_USDC && b["owner"] == expected_address {
            pre_val = b["uiTokenAmount"]["uiAmount"].as_f64().unwrap_or(0.0);
        }
    }
    
    let mut post_val = 0.0;
    for b in post {
        if b["mint"] == SOLANA_USDC && b["owner"] == expected_address {
            post_val = b["uiTokenAmount"]["uiAmount"].as_f64().unwrap_or(0.0);
        }
    }
    
    if (post_val - pre_val - expected_amount).abs() < 0.001 {
        return Ok(true);
    }
    Ok(false)
}
Verification steps:
  1. Fetch transaction details via Solana RPC
  2. Extract preTokenBalances and postTokenBalances from metadata
  3. Find USDC mint in recipient’s token accounts
  4. Calculate balance change
  5. Verify amount matches expected payment

Using Beacon Cloud

CLI Usage

# Generate with Beacon Cloud
beacon generate ./my-project --provider beacon-ai-cloud

# Follow interactive prompts:
# 1. Choose chain (base/solana)
# 2. Send USDC to provided address
# 3. Paste transaction hash
# 4. Wait for verification

API Usage

You can also use Beacon Cloud via the HTTP API:
1

Initial request

Make a POST request without payment headers:
curl -X POST https://beacon-latest.onrender.com/generate \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "beacon-ai-cloud",
    "name": "my-project",
    "readme": "# My Project\n...",
    "source_files": [{"path": "main.rs", "content": "..."}]
  }'
2

Parse payment response

Extract payment details from headers:
HTTP/1.1 402 Payment Required
x-payment-amount: 0.09
x-payment-run-id: 550e8400-e29b-41d4-a716-446655440000
x-payment-address-base: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
x-payment-address-solana: 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin
3

Send payment & retry with headers

After sending USDC, retry with payment proof:
curl -X POST https://beacon-latest.onrender.com/generate \
  -H "Content-Type: application/json" \
  -H "x-payment-run-id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "x-payment-chain: base" \
  -H "x-payment-txn-hash: 0x1234abcd..." \
  -d '{ /* same payload */ }'
4

Receive result

Get the generated AGENTS.md:
{
  "success": true,
  "agents_md": "# AGENTS.md — my-project\n...",
  "manifest": { ... }
}

Configuration

Beacon Cloud settings are configured via environment variables on the server:
BEACON_CLOUD_URL
string
default:"https://beacon-latest.onrender.com"
Override the default Beacon Cloud endpoint.
export BEACON_CLOUD_URL="https://your-beacon-instance.com"
beacon generate . --provider beacon-ai-cloud
PAYMENT_AMOUNT_USDC
string
default:"0.09"
USDC amount to charge per generation (server-side config).
BEACON_WALLET_BASE
string
Base network wallet address for receiving payments (server-side).
BEACON_WALLET_SOLANA
string
Solana wallet address for receiving payments (server-side).

Security Features

Transaction Replay Prevention

Beacon Cloud prevents reusing transaction hashes:
if db::payment_already_used(txn).await.unwrap_or(false) {
    return Err(BeaconError::TransactionAlreadyUsed);
}
Each transaction can only be used once across all runs.

Amount Verification

Payments are verified to match the expected amount:
if (amount_f64 - expected_amount).abs() < 0.001 {
    return Ok(true);
}
Small tolerance (±0.001 USDC) accounts for rounding in on-chain balances.

Address Verification

Payments must go to the correct recipient address:
if to == receiver_addr {
    // Payment verified
}

Benefits

No API Keys

Skip signing up for Gemini/Claude/OpenAI accounts and managing API keys.

Pay Per Use

Only pay when you generate. No monthly subscriptions or minimum commitments.

Crypto Native

Use USDC on Base or Solana—no credit cards, no KYC, no chargebacks.

Transparent Pricing

Fixed $0.09 USDC per generation. No hidden fees or rate limit surprises.

Limitations

Payment is non-refundable once verified. Make sure your repository context is correct before submitting.
Test with the standard providers first (using free API keys) before using Beacon Cloud for production workflows.

Troubleshooting

Payment Not Verified

Possible causes:
  • Wrong chain selected (sent on Base but said Solana)
  • Insufficient amount sent
  • Wrong recipient address
  • Transaction not yet confirmed
Solution:
# Check transaction on block explorer
# Base: https://basescan.org/tx/<hash>
# Solana: https://solscan.io/tx/<hash>

# Verify:
# 1. Transaction succeeded (not failed/pending)
# 2. Sent exactly 0.09 USDC (not 0.09 ETH or SOL)
# 3. Recipient address matches provided address

Transaction Already Used

Error: TransactionAlreadyUsed
You’re trying to reuse a transaction hash that was already verified for another run. Solution: Send a new payment with a fresh transaction.

Timeout Waiting for Payment

Beacon Cloud doesn’t have a timeout—you can send payment anytime after receiving the addresses. Run IDs are persistent in the database, so you can resume payment later by including the same x-payment-run-id header.

Cost Comparison

MethodCost per GenerationSetup Required
Gemini (self-hosted)~$0.002API key, billing
Claude (self-hosted)~$0.015API key, billing
OpenAI (self-hosted)~$0.008API key, billing
Beacon Cloud$0.09USDC wallet only
Beacon Cloud costs more per run but eliminates infrastructure, API key management, and subscription overhead. Best for occasional use or teams that prefer crypto payments.

Running Your Own Instance

You can deploy your own Beacon Cloud instance with payment verification:
# Set wallet addresses
export BEACON_WALLET_BASE="0xYourBaseAddress"
export BEACON_WALLET_SOLANA="YourSolanaAddress"
export PAYMENT_AMOUNT_USDC="0.09"

# Set RPC URLs
export BASE_RPC_URL="https://mainnet.base.org"
export SOLANA_RPC_URL="https://api.mainnet-beta.solana.com"

# Start server
beacon serve --port 8080
See Docker Deployment for full setup instructions.

Next Steps

On-Chain Identity

Register your agent on-chain with ERC-7527

Multiple Providers

Compare Beacon Cloud with other AI providers

Build docs developers (and LLMs) love