How to Create a Beacon

This guide shows you how to create beacons (oracle data feeds) using The Beaconator API.

Create a Basic Beacon

This endpoint is a placeholder and not yet fully implemented.

curl -X POST http://localhost:8000/create_beacon \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "placeholder": "beacon"
  }'

Request Parameters:

placeholder: Placeholder string (endpoint not yet implemented)

Response:

{
  "success": true,
  "data": "0x1234567890123456789012345678901234567890",
  "message": "Beacon created successfully"
}

Create and Register with PerpCity

Create a beacon and automatically register it with the PerpCity registry. This endpoint takes no request body:

curl -X POST http://localhost:8000/create_perpcity_beacon \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "success": true,
  "data": "Beacon address: 0x1234...abcd, tx: 0xabcd...1234",
  "message": "Perpcity beacon created and registered successfully"
}

Batch Create Multiple Beacons

Create multiple beacons in a single request:

curl -X POST http://localhost:8000/batch_create_perpcity_beacon \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "count": 3
  }'

Request Parameters:

count: Number of beacons to create (1-100)

Response:

{
  "success": true,
  "data": {
    "created_count": 3,
    "beacon_addresses": ["0x...", "0x...", "0x..."],
    "failed_count": 0,
    "errors": []
  },
  "message": "Batch beacon creation completed"
}

Batch operations use Multicall3 for gas efficiency. All creations execute atomically in a single transaction.

Create Verifiable Beacon

For beacons that require proof verification with TWAP support:

curl -X POST http://localhost:8000/create_verifiable_beacon \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "verifier_address": "0x1234567890123456789012345678901234567890",
    "initial_data": 560227709747861419891227623424,
    "initial_cardinality": 100
  }'

Request Parameters:

verifier_address: Address of the Halo2 verifier contract
initial_data: Initial data value (must be pre-scaled by 2^96 if representing a decimal)
initial_cardinality: Initial TWAP observation slots (typically 100-1000)

Register Existing Beacon

If you already have a beacon contract, register it with a registry:

curl -X POST http://localhost:8000/register_beacon \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "beacon_address": "0x1234567890123456789012345678901234567890",
    "registry_address": "0xf0cd58b0c706dd6d65468cc08de552e83a709a03"
  }'

Request Parameters:

beacon_address: Address of existing beacon contract
registry_address: Address of the beacon registry contract

Error Handling

All error responses use the standard API response format:

{
  "success": false,
  "data": null,
  "message": "Error description here"
}

Common Errors

Insufficient Gas: Add more ETH to the wallet pool.

Authentication Failed: Check your Authorization header includes the correct Bearer token.

Monitoring Beacon Creation

Track your beacon creation transaction:

// After creating beacon — the data field contains both address and tx hash
const responseData = result.data
// e.g. "Beacon address: 0x1234...abcd, tx: 0xabcd...1234"

// Parse the beacon address from the data string
const beaconAddress = responseData.split('Beacon address: ')[1]?.split(',')[0]

// View on block explorer
console.log(`Beacon Contract: https://basescan.org/address/${beaconAddress}`)

On this page