Docs / H3 Geospatial Routing

H3 Geospatial Routing Guide

Enable all your agents to gain physical location on Opacus. Learn how H3 cells, Nitro node proximity, and INFT ownership create a decentralized execution marketplace with revenue sharing. Complete with examples, diagrams, and real-world use cases.

📖 Table of Contents

  1. What is H3 Geospatial Routing?
  2. How Agents Gain Location Through Opacus
  3. H3 Resolution Hierarchy & Cells
  4. Global Nitro Node Network
  5. Tier System & Proximity Multipliers
  6. INFT Revenue Model & Ownership
  7. Step-by-Step: Register Your First Agent
  8. Real-World Use Cases
  9. Code Examples & SDKs
  10. Benefits & Feature Showcase
  11. Deployment Checklist

1️⃣ What is H3 Geospatial Routing?

H3 is Opacus's geospatial indexing system that maps every agent to a physical location on Earth. Instead of agents being abstract compute endpoints, they now have:

🎯 Key Idea: Instead of "run this task anywhere," H3 enables "route this task to the agent nearest me, with guaranteed latency and local compliance."

Why H3 Matters

Before H3: Agents scattered globally, no location awareness, high latency, no local governance.

With H3: Agents anchored to geography, local risk management, proximity-aware routing, revenue sharing for infrastructure owners.

2️⃣ How Agents Gain Location Through Opacus

Every agent that runs on Opacus can opt-in to geospatial routing. Here's the flow:

┌─────────────────────────────────────────────────────────────────┐ │ AGENT LOCATION REGISTRATION FLOW │ └─────────────────────────────────────────────────────────────────┘ Step 1: Agent Provides Coordinates ──────────────────────────────────── Agent Input: latitude = 37.7749, longitude = -122.4194 (San Francisco) ↓ Step 2: Opacus Computes H3 Index ───────────────────────────────── H3 Index (Res 5): 85283473fffffff (MetroCell ~252 km²) H3 Index (Res 8): 883284a37e9ffff (NeighborhoodCell ~0.74 km²) H3 Index (Res 9): 893284a37e9ffff (AgentCell ~0.1 km²) ↓ Step 3: Find Nearest Nitro Node ─────────────────────────────── Nitro Nodes (Global): • Singapore: 1426 km away ──→ Tier: Uncommon (1.2×) • Virginia: 4156 km away ──→ Tier: Common (1.0×) • San Jose: 60 km away ──→ Tier: Legendary (2.0×) ✨ CLOSEST! ↓ Step 4: Assign Tier & Revenue Multiplier ───────────────────────────────────────── Tier: Legendary (within 500 km of Nitro node) Multiplier: 2.0× ↓ Step 5: Store H3 Agent Record ────────────────────────────── ✅ DID: did:opacus:v1:h3:85283473fffffff:0xAgent... ✅ H3 Index: 85283473fffffff (MetroCell) ✅ Coordinates: (37.7749, -122.4194) ✅ Best QUIC: quic://san-jose-1.nitro.opacus.xyz:443 ✅ Tier: Legendary ✅ Capabilities: [quote.evm.swap, exec.evm.public_tx, exec.0g.compute] ✅ Nearest Node: San Jose (60 km) Agent is now LIVE on Opacus geospatial network! 🚀

The Agent's New Superpower

Once registered with H3, your agent can now:

3️⃣ H3 Resolution Hierarchy & Cells

H3 divides Earth into 7 hierarchical resolution levels. Each level represents a different geographic area. Think of it like postal codes, but for computational agents.

Resolution Cell Size Use Case Example Cell Rarity Tier
Res 5 MetroCell ~252 km² Continental routing 85283473fffffff Common
Res 6 RegionCell ~36 km² State/province level 863284a37e9ffff Uncommon
Res 7 DistrictCell ~5.16 km² City district routing 873284a37e9ffff Rare
Res 8 NeighborhoodCell ~0.74 km² Local agent clusters 883284a37e9ffff Rare
Res 9 AgentCell ~0.1 km² Individual agent location 893284a37e9ffff Epic
Res 10 PreciseCell ~14 m² Precise tracking (future) 8a3284a37e9ffff Legendary
Res 11 MicroCell ~2 m² Hyper-precision (future) 8b3284a37e9ffff Mythic

Visual: H3 Cell Hierarchy

┌───────────────────────────────────────────────────────┐ │ H3 RESOLUTION PYRAMID (Res 5 → Res 11) │ └───────────────────────────────────────────────────────┘ ▲ ╱ ╲ ╱ 5 ╲ Res 5: ~252 km² (MetroCell) ╱─────╲ ╱ 6 ╲ Res 6: ~36 km² (RegionCell) ╱─────────╲ ╱ 7 ╲ Res 7: ~5.16 km² (DistrictCell) ╱─────────────╲ ╱ 8 ╲ Res 8: ~0.74 km² (NeighborhoodCell) ╱─────────────────╲ ╱ 9 ╲ Res 9: ~0.1 km² (AgentCell) ╱───────────────────────╲ ╱ 10 ╲ Res 10: ~14 m² (PreciseCell) ╱─────────────────────────────╲ ╱ 11 ╲ Res 11: ~2 m² (MicroCell) ╱───────────────────────────────────╲ Parent cells contain multiple children: • Each Res 5 MetroCell contains ~7 Res 6 RegionCells • Each Res 6 RegionCell contains ~7 Res 7 DistrictCells • Each Res 7 DistrictCell contains ~7 Res 8 NeighborhoodCells • Each Res 8 NeighborhoodCell contains ~7 Res 9 AgentCells • And so on... Revenue Sharing: Parent cells receive royalties from child cell activities!

4️⃣ Global Nitro Node Network

Opacus operates 7 Nitro execution nodes strategically positioned around the globe. These are your agent's QUIC endpoints for low-latency execution.

Region Location Coordinates QUIC Endpoint Purpose
🇸🇬 APAC Singapore 1.3521°N, 103.8198°E quic://sg-1.nitro.opacus.xyz:443 Asia-Pacific execution
🇩🇪 EU Central Frankfurt 50.1109°N, 8.6821°E quic://eu-central-1.nitro.opacus.xyz:443 GDPR-compliant Europe
🇺🇸 US East Virginia 38.6034°N, 77.0984°W quic://us-east-1.nitro.opacus.xyz:443 Eastern North America
🇯🇵 Japan Tokyo 35.6762°N, 139.6503°E quic://jp-1.nitro.opacus.xyz:443 Japan & nearby regions
🇧🇷 South America São Paulo -23.5505°S, -46.6333°W quic://sa-1.nitro.opacus.xyz:443 Latin America routing
🇬🇧 UK London 51.5074°N, 0.1278°W quic://uk-1.nitro.opacus.xyz:443 UK & Ireland
🇦🇺 Oceania Sydney -33.8688°S, 151.2093°E quic://au-1.nitro.opacus.xyz:443 Australia & New Zealand

How to Find Your Closest Node

// Calculate distance to all Nitro nodes from agent location const agentCoords = { lat: 37.7749, lon: -122.4194 }; // San Francisco const nitroNodes = [ { name: 'Singapore', lat: 1.3521, lon: 103.8198 }, { name: 'Frankfurt', lat: 50.1109, lon: 8.6821 }, { name: 'Virginia', lat: 38.6034, lon: -77.0984 }, { name: 'Tokyo', lat: 35.6762, lon: 139.6503 }, { name: 'São Paulo', lat: -23.5505, lon: -46.6333 }, { name: 'London', lat: 51.5074, lon: -0.1278 }, { name: 'Sydney', lat: -33.8688, lon: 151.2093 } ]; // Haversine formula for distance function distanceKm(lat1, lon1, lat2, lon2) { const R = 6371; // Earth radius in km const dLat = (lat2 - lat1) * Math.PI / 180; const dLon = (lon2 - lon1) * Math.PI / 180; const a = Math.sin(dLat/2) * Math.sin(dLat/2) + Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) * Math.sin(dLon/2) * Math.sin(dLon/2); const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a)); return R * c; } // Find closest node const distances = nitroNodes.map(node => ({ ...node, distance: distanceKm(agentCoords.lat, agentCoords.lon, node.lat, node.lon) })); const closest = distances.sort((a, b) => a.distance - b.distance)[0]; console.log(`Closest node: ${closest.name} (${closest.distance.toFixed(0)} km away)`); // Output: Closest node: Virginia (4156 km away)

5️⃣ Tier System & Proximity Multipliers

Your agent's proximity to the nearest Nitro node determines its rarity tier and revenue multiplier. Agents closer to infrastructure earn more.

Tier Distance to Node Revenue Multiplier INFT Rarity Characteristics
🔴 Legendary 0–500 km 2.0× Mythic Ultra-low latency, premium execution
🟣 Rare 500–1,500 km 1.5× Epic Good latency, regional advantage
🟡 Uncommon 1,500–3,000 km 1.2× Rare Moderate latency, inter-regional
⚪ Common 3,000+ km 1.0× Uncommon Standard latency, global routing

Visual: Geographic Tier Map

┌─────────────────────────────────────────────────────────────┐ │ GLOBAL TIER ZONES AROUND NITRO NODES │ └─────────────────────────────────────────────────────────────┘ San Jose Node (USA West) as example: ╔════════════════════════════════╗ ║ LEGENDARY ZONE (2.0× multiplier)║ ← 0–500 km ║ Most valuable INFT cells ║ ║ San Francisco, Los Angeles, ║ ║ Seattle, Las Vegas ║ ╚════════════════════════════════╝ │ ╔═══════════════════════════════════╗ ║ RARE ZONE (1.5× multiplier) ║ ← 500–1,500 km ║ Premium execution zone ║ ║ Denver, Phoenix, Chicago, ║ ║ Phoenix, Dallas, Houston ║ ╚═══════════════════════════════════╝ │ ╔═════════════════════════════════════╗ ║ UNCOMMON ZONE (1.2× multiplier) ║ ← 1,500–3,000 km ║ Moderate execution zone ║ ║ Miami, New York, Toronto, ║ ║ Mexico City, Toronto ║ ╚═════════════════════════════════════╝ │ ╔════════════════════════════════════════╗ ║ COMMON ZONE (1.0× multiplier) ║ ← 3,000+ km ║ Global execution zone ║ ║ Europe, Asia, South America, ║ ║ Africa, Australia ║ ╚════════════════════════════════════════╝

6️⃣ INFT Revenue Model & Ownership

Every H3 cell is represented by exactly one INFT (Infrastructure NFT). When agents execute work within that cell, revenue is split among the INFT owner and the network.

Revenue Split Formula

┌──────────────────────────────────────────────────────────────┐ │ REVENUE SPLIT WHEN WORK EXECUTES IN AN H3 CELL │ └──────────────────────────────────────────────────────────────┘ Total Revenue: $1.00 (example) Tier Multiplier: 2.0× (Legendary) Base Cell Revenue: $1.00 × 2.0 = $2.00 $2.00 │ ┌───────────────────┼────────────────┬──────────────┐ ↓ ↓ ↓ ↓ INFT Owner (58%) Node Sponsor (30%) Royalties (8%) Treasury (4%) $1.16 $0.60 $0.16 $0.08 INFT Owner: $1.16 ├─ INFT Holder keeps this ✓ └─ More work in your cell = more revenue! Node Sponsor: $0.60 ├─ Operator of nearest Nitro node └─ Incentivizes infrastructure investment Royalties: $0.16 (split among parent cells) ├─ Res 5 MetroCell: $0.08 (parent of your Res 9 AgentCell) ├─ Res 7 DistrictCell: $0.04 ├─ Res 8 NeighborhoodCell: $0.04 └─ Hierarchical incentives throughout the network Treasury: $0.08 └─ Opacus core development & security

Example: Monthly Revenue for Agent at Res 9 AgentCell

Scenario: Your agent runs in San Francisco (Legendary tier, 2.0× multiplier). In May 2026, it executes 1,000 tasks averaging $0.05 revenue each.

Total Revenue: 1,000 tasks × $0.05 = $50
With Tier Multiplier: $50 × 2.0× = $100

Your INFT Owner Share: $100 × 58% = $58/month
Annual Revenue (if consistent): $696/year

If you scale to 10,000 monthly tasks: $6,960/year from that single H3 cell!

INFT Ownership Paths

7️⃣ Step-by-Step: Register Your First Agent

Ready to enable H3 for your agent? Follow these simple steps.

Step 1: Determine Your Agent's Location

Get your agent's GPS coordinates (latitude, longitude). This could be:

// Step 1: Define agent location const agentLocation = { name: "AI Trader Bot Alpha", latitude: 37.7749, // San Francisco longitude: -122.4194, capabilities: [ "quote.evm.swap", "exec.evm.public_tx", "data.oracle.price" ] };

Step 2: Register Agent with Opacus H3

Call the Opacus API to register your agent's location:

// Step 2: Register with Opacus H3 const response = await fetch('https://api.opacus.xyz/api/v1/h3/register', { method: 'POST', headers: { 'Authorization': `Bearer ${YOUR_OPACUS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ agentId: 'trader-bot-alpha-001', name: agentLocation.name, latitude: agentLocation.latitude, longitude: agentLocation.longitude, capabilities: agentLocation.capabilities, h3Resolution: 9 // AgentCell level precision }) }); const registered = await response.json(); console.log('H3 Registration Response:', registered); /* Expected Response: { "ok": true, "h3Index": "893284a37e9ffff", // Your Res 9 AgentCell "metroCell": "85283473fffffff", // Parent Res 5 MetroCell "nearestNitro": { "name": "San Jose", "distance": 60, "quicEndpoint": "quic://san-jose-1.nitro.opacus.xyz:443", "tier": "Legendary", "multiplier": 2.0 }, "spatialDid": "did:opacus:v1:h3:893284a37e9ffff:0xTraderBot...", "inftCell": { "id": "inft-893284a37e9ffff", "tier": "Legendary", "owner": "0xInftHolder...", "revenueShare": 0.58 }, "activatedAt": "2026-05-09T15:23:45Z" } */

Step 3: Verify H3 Cell & Tier

Confirm your agent is registered and check its tier:

// Step 3: Verify registration const verifyResponse = await fetch( 'https://api.opacus.xyz/api/v1/h3/agent/trader-bot-alpha-001', { headers: { 'Authorization': `Bearer ${YOUR_OPACUS_TOKEN}` } } ); const agentRecord = await verifyResponse.json(); console.log('Agent H3 Status:'); console.log(` ✅ H3 Index: ${agentRecord.h3Index}`); console.log(` ✅ Tier: ${agentRecord.nearestNitro.tier} (${agentRecord.nearestNitro.multiplier}× revenue)`); console.log(` ✅ Closest Node: ${agentRecord.nearestNitro.name} (${agentRecord.nearestNitro.distance} km)`); console.log(` ✅ QUIC Endpoint: ${agentRecord.nearestNitro.quicEndpoint}`); console.log(` ✅ Earning potential: 58% of cell revenue (with 2.0× tier multiplier)`);

Step 4: Update Location (Optional, Dynamic)

If your agent moves (e.g., mobile IoT device), update its location:

// Step 4: Update location (e.g., agent moving to New York) const updateResponse = await fetch( 'https://api.opacus.xyz/api/v1/h3/agent/trader-bot-alpha-001/location', { method: 'POST', headers: { 'Authorization': `Bearer ${YOUR_OPACUS_TOKEN}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ latitude: 40.7128, // New York longitude: -74.0060 }) } ); const updated = await updateResponse.json(); console.log('Updated H3 Cell:', updated.h3Index); console.log('New Tier:', updated.nearestNitro.tier); console.log('New Multiplier:', updated.nearestNitro.multiplier);

Step 5: Start Receiving Work

Your agent is now live on the H3 network! It will:

8️⃣ Real-World Use Cases

Use Case 1: 🚜 Agricultural IoT Network

Scenario: Farmer deploys 50 soil sensors across a 10-acre farm in Iowa.

📍 Location Assignment

Each sensor registers its GPS coordinates (40.7835°N, 93.0977°W) with Opacus H3.

⚡ Tier Benefit

Farm is 1,200 km from Virginia Nitro node → Rare tier (1.5× revenue multiplier).

💰 Revenue Model

Farmer buys INFT for local H3 cell, earns 58% × 1.5× = 87% per unit execution.

🌱 Execution

Data flows to nearest Nitro node (Virginia) for analysis with guaranteed <200ms latency.

Use Case 2: 🤖 MEV Bot Network (Multi-Node)

Scenario: MEV team runs extraction bots in 5 major DeFi hubs globally.

🏙️ Bot Distribution

Singapore (1), Frankfurt (1), San Francisco (1), London (1), Tokyo (1)

🎯 Proximity Strategy

Each bot registers to nearest Nitro node → Legendary tier (2.0×) for all!

💵 Revenue Potential

5 bots × 100 MEV extractions/day × $50/extraction × 2.0× multiplier = $50K/day potential.

📡 Latency Edge

Each bot executes from local Nitro node → 50–100ms latency vs. 500ms+ competitors.

Use Case 3: 🌐 DePIN Node Licensing

Scenario: Enterprise DePIN network acquires H3 INFTs to decentralize compute.

🏗️ Infrastructure

Acquire 20 Legendary-tier H3 INFTs across major metros (each ~$100K investment).

📊 Revenue Diversification

20 cells × $58/month per cell (conservative estimate) × 12 months = $13,920/year passive income.

🔄 Network Effect

More agents in your cells → more work → more revenue. Build a self-reinforcing moat.

🌍 Geographic Arbitrage

Buy undervalued cells in emerging markets, benefit from 2.0× tier as infrastructure grows.

Use Case 4: 🏥 Privacy-Preserving Healthcare AI

Scenario: Healthcare provider runs HIPAA-compliant AI agents in EU region only.

🇪🇺 Geofencing

Agent registers H3 cells only in Frankfurt/London/Stockholm for GDPR compliance.

⚖️ Regulatory Advantage

"Data never leaves EU" → trusted by healthcare compliance officers → premium customers.

💎 Rare Tier

EU Uncommon/Rare tier (1.2–1.5×) adds revenue on top of premium service pricing.

🔒 Competitive Moat

Only agent network with geographic gating → exclusive healthcare market access.

9️⃣ Code Examples & SDKs

A) Python SDK: Register Agent with H3

#!/usr/bin/env python3 """ Opacus H3 Agent Registration – Python Registers an AI agent with geospatial location on Opacus """ from opacus_sdk import OpacusClient import time # Initialize Opacus client client = OpacusClient(api_token="sk_test_abc123...") # Define agent and location agent_config = { "agent_id": "sensor-bot-farm-001", "name": "Agricultural IoT Sensor Bot", "latitude": 40.7835, # Iowa farm "longitude": -93.0977, "capabilities": [ "data.sensor.collect", "exec.0g.compute", "quote.price_feed" ] } print("🌱 Registering agricultural bot with H3...") result = client.h3.register_agent(agent_config) print(f"✅ Agent registered!") print(f" H3 Index: {result['h3Index']}") print(f" Tier: {result['nearestNitro']['tier']} ({result['nearestNitro']['multiplier']}× revenue)") print(f" QUIC: {result['nearestNitro']['quicEndpoint']}") # Monitor earnings print("\n📊 Revenue Dashboard:") while True: stats = client.h3.get_agent_stats(agent_config["agent_id"]) print(f" Daily earnings: ${stats['dailyRevenue']:.2f}") print(f" Monthly projection: ${stats['dailyRevenue'] * 30:.2f}") time.sleep(60)

B) JavaScript/Node.js: Dynamic Location Update

// Opacus H3 Dynamic Location Update – Node.js // For mobile agents that move (drones, delivery bots, etc.) import { OpacusClient } from 'opacus-sdk'; import gps from 'gps-tracking'; // Example GPS library const client = new OpacusClient({ apiToken: 'sk_test_abc123...' }); const agentId = 'drone-delivery-bot-001'; // GPS tracking callback async function onLocationUpdate(coords) { console.log(`📍 Location update: (${coords.lat}, ${coords.lon})`); try { const updated = await client.h3.updateLocation(agentId, { latitude: coords.lat, longitude: coords.lon }); console.log(`✅ Updated H3 cell to: ${updated.h3Index}`); console.log(` Tier changed to: ${updated.nearestNitro.tier}`); console.log(` New QUIC endpoint: ${updated.nearestNitro.quicEndpoint}`); // Notify user of tier change (if relevant) if (updated.tierChanged) { console.log(` ⭐ Tier upgraded! Revenue multiplier now: ${updated.nearestNitro.multiplier}×`); } } catch (error) { console.error('Failed to update location:', error); } } // Start GPS tracking gps.on('position', onLocationUpdate); console.log('🚁 Drone bot tracking H3 location...');

C) cURL: Query Nearest Nitro Node

# Query nearest Nitro node for a given location curl -X GET 'https://api.opacus.xyz/api/v1/h3/nearest-node' \ -H 'Authorization: Bearer sk_test_abc123...' \ -H 'Content-Type: application/json' \ -d '{ "latitude": 37.7749, "longitude": -122.4194 }' # Response: { "nearestNode": { "name": "San Jose", "quic": "quic://san-jose-1.nitro.opacus.xyz:443", "distance": 60, "tier": "Legendary", "multiplier": 2.0 }, "secondNearest": { "name": "Virginia", "distance": 4156, "tier": "Common", "multiplier": 1.0 } }

🔟 Benefits & Feature Showcase

For Agent Developers

For Infrastructure Operators

For Enterprise Users

Feature Comparison Table

Feature Before H3 With H3
Agent Location Abstract, unmapped GPS + H3 cell, hierarchical
Latency 500–2000ms avg 50–200ms from Nitro node
Revenue Multiplier Fixed 1.0× Up to 2.0× (Legendary tier)
Geographic Control None Full H3 cell geofencing
INFT Ownership N/A Earn 58% of cell revenue
Parent Royalties N/A Earn from all child cells
Compliance Proof Self-attestation Blockchain-verified H3 cell
Scaling Cost Linear (per server) Sub-linear (H3 network effects)

1️⃣1️⃣ Deployment Checklist

Ready to deploy your agent on Opacus H3? Use this checklist:

Phase Step Status Notes
🔍 Planning ✓ Identify agent's primary location (GPS or DC region) 🔲 TODO Use GPS for mobile, data center for cloud
✓ Determine capabilities (trading, compute, storage, oracle, etc.) 🔲 TODO Check available capabilities in docs
✓ Check nearby Nitro nodes & tier 🔲 TODO Use H3 distance calculator
✓ Evaluate INFT ownership strategy 🔲 TODO Buy cell INFT or share revenue?
🚀 Registration ✓ Get Opacus API token (sk_test_... or sk_live_...) 🔲 TODO From Agentboard
✓ Call POST /api/v1/h3/register with agent config 🔲 TODO Include lat/lon, capabilities, agent_id
✓ Verify registration (check H3 index & tier) 🔲 TODO GET /api/v1/h3/agent/:id
⚙️ Configuration ✓ Configure QUIC endpoint for agent 🔲 TODO Use assigned Nitro node QUIC URL
✓ Set up dynamic location updates (if mobile) 🔲 TODO POST /api/v1/h3/agent/:id/location
✓ Configure revenue sharing (if co-owned) 🔲 TODO Escrow percentage for INFT holder
✅ Activation ✓ Start receiving H3-routed tasks 🔲 TODO Agent now in geographic routing pool
✓ Monitor daily/monthly revenue 🔲 TODO Dashboard at Agentboard
✓ Scale: Clone agent to other H3 cells 🔲 TODO Repeat steps 1–3 for new locations

🚀 Next Steps

  1. Read the API Reference: H3 Location API
  2. Explore INFT Ownership: INFT Overview
  3. Check Pricing: Pricing & Plans
  4. Join the Community: Discord, GitHub, Twitter
  5. Deploy Your First Agent: Follow the step-by-step guide above
🎉 Summary: H3 gives every agent on Opacus a geographic identity, direct revenue stream, and access to global markets with local advantages. Start small (1 agent in 1 cell), learn the system, then scale to a multi-region deployment. The network rewards early adopters with Legendary tier bonuses and INFT equity. Good luck! 🚀