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:
Make a generation request
Call Beacon with --provider beacon-ai-cloud. No API key needed. beacon generate ./my-project --provider beacon-ai-cloud
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
Send USDC payment
Transfer USDC to the provided address using your wallet (MetaMask, Phantom, etc.).
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...
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 :
Fetch transaction receipt from Base RPC
Check transaction status is successful
Parse ERC-20 Transfer event logs
Verify recipient address matches
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 :
Fetch transaction details via Solana RPC
Extract preTokenBalances and postTokenBalances from metadata
Find USDC mint in recipient’s token accounts
Calculate balance change
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:
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": "..."}]
}'
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
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 */ }'
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
USDC amount to charge per generation (server-side config).
Base network wallet address for receiving payments (server-side).
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
Method Cost per Generation Setup Required Gemini (self-hosted) ~$0.002 API key, billing Claude (self-hosted) ~$0.015 API key, billing OpenAI (self-hosted) ~$0.008 API key, billing Beacon Cloud $0.09 USDC 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