Get All Actors
Fetch all registered actors from the ActorRegistry contract.
curl https://proteus-production-6213.up.railway.app/api/chain/actors
Array of actor objects from blockchain
Total number of actors returned
Always "blockchain" - indicates data source
Response
{
"actors": [
{
"address": "0x1234567890abcdef1234567890abcdef12345678",
"name": "Elon Musk",
"x_username": "elonmusk",
"verified": true,
"block_number": 12345000
},
{
"address": "0x9876543210fedcba9876543210fedcba98765432",
"name": "Vitalik Buterin",
"x_username": "VitalikButerin",
"verified": true,
"block_number": 12346000
}
],
"total": 2,
"source": "blockchain"
}
Actor data is fetched from ActorRegistered events emitted by the ActorRegistry contract. The API queries historical events and enriches them with current on-chain state using the getActor() contract method.
Actor Object Fields
Ethereum address of the actor (can be zero address for unlinked actors)
Display name of the actor (e.g., “Elon Musk”)
X.com (Twitter) username without @ symbol
Whether the actor has been verified by the platform
Block number when the actor was registered
Actor Verification
Actors must be verified before markets can be created for them. Verification is handled on-chain by the ActorRegistry contract owner.
Check if Actor is Verified
import { ethers } from 'ethers';
const actorRegistryABI = [
"function getActor(address actorAddress) view returns (string name, string xUsername, bool verified)"
];
const provider = new ethers.JsonRpcProvider('https://sepolia.base.org');
const actorRegistry = new ethers.Contract(
'0xC71CC19C5573C5E1E144829800cD0005D0eDB723',
actorRegistryABI,
provider
);
const actorAddress = '0x1234567890abcdef1234567890abcdef12345678';
const [name, xUsername, verified] = await actorRegistry.getActor(actorAddress);
console.log('Actor:', name);
console.log('X Username:', xUsername);
console.log('Verified:', verified);
Register New Actor
To register a new actor, you must interact directly with the ActorRegistry contract.
Contract Method
function registerActor(
address actorAddress,
string memory name,
string memory xUsername
) external
Ethereum address of the actor (use zero address if unknown)
Display name (e.g., “Elon Musk”)
X.com username without @ symbol (e.g., “elonmusk”)
Any address can register an actor, but the actor will not be verified until the contract owner approves them. Only verified actors can have markets created for them.
Using Web3.js
import { ethers } from 'ethers';
const actorRegistryABI = [
"function registerActor(address actorAddress, string memory name, string memory xUsername) external"
];
const provider = new ethers.BrowserProvider(window.ethereum);
const signer = await provider.getSigner();
const actorRegistry = new ethers.Contract(
'0xC71CC19C5573C5E1E144829800cD0005D0eDB723',
actorRegistryABI,
signer
);
// Register actor
const tx = await actorRegistry.registerActor(
'0x0000000000000000000000000000000000000000', // Zero address (unknown wallet)
'Elon Musk',
'elonmusk'
);
const receipt = await tx.wait();
console.log('Actor registered:', receipt.transactionHash);
Get Genesis NFT Holders
Fetch addresses holding Genesis NFTs (relevant for platform governance).
curl https://proteus-production-6213.up.railway.app/api/chain/genesis/holders
Array of Genesis NFT holder data
Ethereum address of the holder
Number of Genesis NFTs held
holders[].percentage_owned
Percentage of total supply owned (out of 100 total)
Total number of unique holders
Total Genesis NFT supply (100)
Response
{
"holders": [
{
"address": "0xholder1234567890abcdef1234567890abcdef1234",
"token_count": 5,
"token_ids": [1, 5, 12, 23, 45],
"percentage_owned": 5
},
{
"address": "0xholder2222222222abcdef1234567890abcdef2222",
"token_count": 3,
"token_ids": [2, 8, 15],
"percentage_owned": 3
}
],
"total_holders": 42,
"total_supply": 100,
"source": "blockchain"
}
Genesis NFT holders get:
- Higher rate limits (500 req/min vs 100 req/min)
- Platform fee share (percentage of all market fees)
- Governance rights (future feature)
Contract Events
The ActorRegistry contract emits these events:
ActorRegistered
event ActorRegistered(
address indexed actorAddress,
string name,
string xUsername,
address indexed registeredBy
);
ActorVerified
event ActorVerified(
address indexed actorAddress,
bool verified
);
Listening to Events
import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider('https://sepolia.base.org');
const actorRegistry = new ethers.Contract(
'0xC71CC19C5573C5E1E144829800cD0005D0eDB723',
actorRegistryABI,
provider
);
// Listen for new actor registrations
actorRegistry.on('ActorRegistered', (actorAddress, name, xUsername, registeredBy) => {
console.log('New actor registered:');
console.log('Address:', actorAddress);
console.log('Name:', name);
console.log('X Username:', xUsername);
console.log('Registered by:', registeredBy);
});
// Query historical registrations
const filter = actorRegistry.filters.ActorRegistered();
const events = await actorRegistry.queryFilter(filter, 0, 'latest');
events.forEach(event => {
console.log('Actor:', event.args.name, '@' + event.args.xUsername);
});
Error Handling
{
"actors": [],
"total": 0,
"source": "blockchain",
"error": "Could not query actor events"
}
- Empty response - Contract not deployed or no actors registered yet
- RPC timeout - BASE network connectivity issue
- Contract not available - ActorRegistry address not configured
Contract Address
BASE Sepolia (Testnet)
0xC71CC19C5573C5E1E144829800cD0005D0eDB723
BASE Mainnet
Not yet deployed.
Best Practices
- Cache actor data - Actor list changes infrequently (5 min TTL recommended)
- Verify actors exist before creating markets
- Check verification status before allowing market creation
- Handle empty responses gracefully (new deployments may have no actors)
- Use lowercase comparisons for X usernames (case-insensitive)