Version: 2.0 Date: April 14, 2026 Protocol: v2.2 Status: Active
Get your first Beacon or Scout running in under 15 minutes.
| I want to… | Start here |
|---|---|
| Sell products/services (Beacon) | Step 1: Create a Beacon |
| Find products/services (Scout) | Step 4: Create a Scout |
| Understand the architecture | Architecture Overview |
| Read the protocol spec | Protocol Specification |
A Beacon is a selling agent that represents a merchant. It registers with AURA Core, receives interpreted requests from Scouts, and submits offers.
npm install @aura-labs-ai/beacon
Before creating an agent, register the principal — the legal entity or individual the agent represents. A principal can present identity credentials from trusted providers for higher trust levels, or register at L0 (self-declared) to get started immediately.
import { createBeacon } from '@aura-labs-ai/beacon';
const beacon = createBeacon({
coreUrl: 'https://aura-labsai-production.up.railway.app',
});
// Register a principal (L0 — no credentials required to start)
const principal = await beacon.registerPrincipal({
principalType: 'organization',
displayName: 'My Demo Store',
});
// principal.principalId = "prn_01H..."
// principal.trustLevel = "self_declared"
To achieve higher trust levels (required for clearinghouse participation), present credentials from trusted providers:
// Present a vLEI credential for L2 (entity_verified)
await beacon.presentCredential(principal.principalId, {
format: 'vlei',
credential: 'eyJhbGciOiJFZERTQSIs...',
});
// trustLevel is now "entity_verified"
See Protocol Foundation Section 3.1 for the full credential model.
// Register the Beacon agent bound to the principal
await beacon.register({
principalId: principal.principalId,
capacity: 'agent_for_principal',
name: 'MyDemoStoreBeacon',
categories: ['electronics', 'home_appliances'],
webhookUrl: 'https://mystore.example.com/aura/webhook',
});
console.log('Beacon registered:', beacon.beaconId);
console.log('Bound to principal:', principal.principalId);
// Define product catalog for intent matching
const catalog = [
{ name: 'Wireless Headphones Pro', sku: 'HP-001', category: 'electronics', tags: ['wireless', 'ANC', 'over-ear'], price: 299.99 },
{ name: 'Wired Earbuds', sku: 'EB-001', category: 'electronics', tags: ['wired', 'earbuds', 'compact'], price: 49.99 },
];
// Poll for sessions and submit offers
beacon.onSession(async (session) => {
// NLP-powered matching against your catalog
const result = await beacon.interpretIntent(session.intent.raw, catalog);
if (result.matches.length > 0 && result.matches[0].score > 30) {
const topMatch = result.matches[0];
await beacon.submitOffer(session.sessionId, {
product: { name: topMatch.item.name, sku: topMatch.item.sku },
unitPrice: topMatch.item.price,
quantity: 1,
currency: 'USD',
});
}
});
// Start polling for sessions
await beacon.start();
// Listen for committed transactions
beacon.onTransaction(async (transaction) => {
console.log('Transaction committed:', transaction.transactionId);
// Mark as delivered when shipped
await beacon.updateFulfillment(transaction.transactionId, {
status: 'delivered',
trackingNumber: 'TRACK-12345',
});
});
# Check health
curl http://localhost:3000/health
# View your inventory (if running local server)
curl http://localhost:3000/inventory
Or use the AURA Core API directly:
# List available sessions for your Beacon
curl -H "X-Agent-ID: <your-agent-id>" \
-H "X-Signature: <ed25519-signature>" \
-H "X-Timestamp: <iso-timestamp>" \
https://aura-labsai-production.up.railway.app/v1/beacons/sessions
Scout AURA Core Beacon
| | |
|--- POST /v1/sessions --->| |
| {intent, constraints} |--- Interpreted Request ->|
| | (projected, not full) |
| |<-- POST offer ----------|
|<-- Ranked offers --------| (signed, Ed25519) |
| | |
|--- POST commit --------->| |
| {offer_id, authority} |--- Settlement Instr. --->| (Rail)
| |<-- Proof of Settlement --| (Rail)
|<-- Confirmation ---------| |
Key principles:
A Scout is a buying agent that represents a consumer or procurement team.
npm install @aura-labs-ai/scout
import { createScout } from '@aura-labs-ai/scout';
const scout = createScout({
coreUrl: 'https://aura-labsai-production.up.railway.app',
});
// Register principal (L0 for browsing — no credential needed)
const principal = await scout.registerPrincipal({
principalType: 'individual',
displayName: 'Jane',
});
// Register the Scout agent
await scout.register({
principalId: principal.principalId,
capacity: 'agent_for_principal',
name: 'JaneShoppingAssistant',
});
await scout.ready();
// Create a session with natural language intent
const session = await scout.intent('I need wireless headphones under $150 with ANC', {
constraints: { maxPrice: 150, category: 'electronics' },
});
// Wait for offers
const offers = await session.waitForOffers({ timeout: 30000 });
console.log(`Received ${offers.length} offers:`);
offers.forEach(offer => {
console.log(` ${offer.product.name} — $${offer.unitPrice} (CWR: ${offer.cwrScore})`);
});
// Select and commit to the best offer
const bestOffer = offers[0]; // Already ranked by CWR
const transaction = await session.commit(bestOffer.offerId, {
authority: {
consentTier: 'explicit',
delegationScopeId: scout.defaultScope.scopeId,
},
shippingAddress: { /* ... */ },
});
console.log('Transaction:', transaction.transactionId);
console.log('Status:', transaction.status); // "committed"
For complex purchases, use IntentSession to validate completeness before submitting:
const intentSession = scout.createIntentSession();
let result = await intentSession.submit('I want headphones');
// { complete: false, missing: ['how_many', ...], question: 'How many do you need?' }
result = await intentSession.submit('2 pairs under $300 by next week');
// { complete: true, missing: [], confidence: 0.91 }
// Submit the complete intent with attestation
const session = await scout.intent(intentSession.getText(), {
completeness: intentSession.getAttestation(),
});
| Concept | Description | Learn More |
|---|---|---|
| Principal | The legal entity or individual behind an agent. Established via external credentials. | Protocol Foundation Section 3.1 |
| Trust Level | L0 (self-declared) through L3 (KYC-verified). Derived from credentials, not AURA verification. | Protocol Foundation Section 3.1.2 |
| CWR | Compatibility-Weighted Reputation — how offers are ranked (reputation x compatibility x risk). | Commerce Protocol Section 9 |
| Market Profile | Configures protocol behavior per market context (retail, B2B, digital goods, services). | Market Profiles Architecture |
| Disclosure Projection | Beacons see a projection of Scout intent, not the full request. Privacy by design. | Commerce Protocol Section 6.6 |
| Settlement Rails | AURA produces settlement instructions; payment rails move money and return proof. | Settlement Rails Architecture |
coreUrl is correct (HTTPS, not WebSocket)beacon.agentId)GET /v1/principals/{id})collecting_offers state| Version | Date | Changes |
|---|---|---|
| 2.0 | 2026-04-14 | Full rewrite for Protocol v2.2. Added principal registration with credential model (DEC-049). Updated all code examples to use REST API with Ed25519 auth (not WebSocket). Added Scout path. Added Key Concepts table. Removed stale WebSocket messaging examples. Updated commerce flow diagram with settlement. |
| 1.0 | 2026-03-11 | Initial quickstart — simple Beacon example with WebSocket connection. |