Skip to main content

​
Overview

Beacon’s API authentication model is designed to be simple yet flexible. The API endpoints themselves do not require authentication, but AI provider API keys must be configured on the server side to enable inference capabilities.

​
API Endpoint Authentication

The Beacon REST API endpoints (/generate, /validate, /health) do not require API keys, tokens, or other authentication headers from clients.
This means you can call the API without including authentication headers: 
curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{"name": "my-repo", ...}'

​
AI Provider Configuration

While the API endpoints are open, Beacon requires AI provider API keys to perform repository analysis and capability inference. These keys must be configured server-side as environment variables.

​
Supported AI Providers

Beacon supports multiple AI providers:

Google Gemini

Default provider - Fast and reliable

Anthropic Claude

High-quality analysis

OpenAI

GPT-4 powered inference

Beacon Cloud

Hosted service with payment

​
Environment Variables

Configure AI provider keys on the server running Beacon:
.env
# Google Gemini (default)
GEMINI_API_KEY=your_gemini_api_key_here

# Anthropic Claude
CLAUDE_API_KEY=your_claude_api_key_here

# OpenAI
OPENAI_API_KEY=your_openai_api_key_here

# Redis (required for rate limiting)
REDIS_URL=redis://localhost:6379

# Beacon Cloud wallets (for payment verification)
BEACON_WALLET_BASE=0x...
BEACON_WALLET_SOLANA=...
PAYMENT_AMOUNT_USDC=0.09

​
Selecting a Provider

Clients specify which provider to use via the provider field in the request body: 
{
  "name": "my-project",
  "source_files": [...],
  "provider": "gemini"  // or "claude", "openai", "beacon-ai-cloud"
}
If no provider is specified, Beacon defaults to "gemini".

​
Beacon Cloud Payment

When using the beacon-ai-cloud provider, requests require cryptocurrency payment verification. This is handled through special HTTP headers.

​
Payment Flow

  1. Initial Request - Make a request without payment headers
  2. Payment Required Response - Server returns 402 with payment details
  3. Complete Payment - Send USDC to the provided wallet address
  4. Retry with Headers - Include payment verification headers

​
Payment Headers

After completing payment on-chain, include these headers in your request:
HeaderTypeRequiredDescription
x-payment-txn-hashstringYesBlockchain transaction hash of the USDC payment
x-payment-chainstringYesBlockchain network used ("base" or "solana")
x-payment-run-idstringYesUnique run ID from the initial 402 response

​
Payment Example

1

Initial Request

Make a request to generate an AGENTS.md file using Beacon Cloud:
curl -X POST https://api.beacon.cloud/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-repo",
    "source_files": [...],
    "provider": "beacon-ai-cloud"
  }'
2

Receive Payment Details

The server responds with 402 Payment Required and payment information:
{
  "success": false,
  "error": "Payment required"
}
Response headers:
x-payment-run-id: run_abc123def456
x-payment-amount: 0.09
x-payment-currency: USDC
x-payment-address-base: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1
x-payment-address-solana: 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
3

Complete Payment

Send the specified amount of USDC to one of the wallet addresses on your preferred chain.
4

Retry with Payment Headers

Include the payment verification headers:
curl -X POST https://api.beacon.cloud/generate \
  -H "Content-Type: application/json" \
  -H "x-payment-txn-hash: 0xabcdef..." \
  -H "x-payment-chain: base" \
  -H "x-payment-run-id: run_abc123def456" \
  -d '{
    "name": "my-repo",
    "source_files": [...],
    "provider": "beacon-ai-cloud"
  }'
5

Receive Response

If payment is verified, the server processes your request and returns the generated AGENTS.md.

​
Payment Verification

The server verifies payments by:
  1. Checking the transaction hash hasn’t been used before
  2. Querying the blockchain to confirm the transaction
  3. Validating the payment amount matches the required USDC amount
  4. Verifying the payment was sent to the correct wallet address
  5. Recording the payment to prevent reuse
Each transaction hash can only be used once. Attempting to reuse a transaction hash will result in a 409 Conflict error.

​
Security Best Practices

  • Store API keys in environment variables, never in code
  • Use .env files for local development (add to .gitignore)
  • Use secret management systems in production (AWS Secrets Manager, HashiCorp Vault, etc.)
  • Rotate keys periodically
  • Run the Beacon server behind a reverse proxy (nginx, Caddy)
  • Use HTTPS/TLS in production
  • Implement additional authentication if exposing publicly
  • Monitor rate limits and unusual usage patterns
  • Always verify transaction hashes on-chain before trusting
  • Never skip payment verification in production
  • Monitor wallet addresses for unexpected transactions
  • Keep payment amount environment variables up to date

​
Rate Limiting

Rate limiting is IP-based and applies to /generate and /validate endpoints:
Limit: 20 requests per 60-second window per IP address
Rate limiting requires Redis to be configured: 
REDIS_URL=redis://localhost:6379
When rate limited, the API returns: 
HTTP/1.1 429 Too Many Requests

​
Next Steps

API Overview

Learn about the Beacon API fundamentals

Generate Endpoint

Start generating AGENTS.md files

Environment Setup

Configure your Beacon server

AI Providers

Compare AI provider options

Build docs developers (and LLMs) love

Get started for freeTalk to us