H3 Location API

1. Overview

The H3 API maps agents to geo-spatial cells (resolution 5 by default) and routes work to the nearest execution zone. Opacus keeps DID as the canonical identity and now supports optional ERC-7857 bindings so NFT-based agents can use the same H3 location pipeline without changing DID format.

2. Identity Model (No DID Breakage)

• Canonical identity: did:opacus:v1:... and did:opacus:v1:h3:<h3Index>:<wallet>
• Optional adapter: ERC-7857 reference can be attached to an H3 agent record.
• Result: Existing Opacus DID flows remain unchanged; ERC-7857 agents can still register/update location.

3. Use Cases

• Assigning geolocation to NFT-native (ERC-7857) agents without redesigning identity.
• Routing tasks to nearest agents by H3 cell + capability filters.
• Re-assigning QUIC endpoint after physical location updates.
• Maintaining one control plane for both DID-native and NFT-linked agents.

4. Pricing

• Price: $0.0002 per call (base)
• Min Lock: $8 / project
• Discounts: Scales down to $0.00010 for >20M monthly calls.

5. API

JSON-RPC Endpoint

POST /api/kinetic/mcp or /api/kinetic/mcp/rpc

Use MCP tool methods below inside JSON-RPC payloads.

kineti_h3_register_agent

Registers/updates an H3 agent. Supports DID-only mode and DID+ERC-7857 adapter mode.

Key Params:

• name (string, optional)
• latitude, longitude (number, optional but recommended)
• capabilities (string[])
• agentId or h3AgentId (optional, for explicit update)
• erc7857Contract (optional)
• erc7857TokenId (optional)
• erc7857ChainId (optional, default 16601)

kineti_h3_location_update

Updates H3 cell, coordinates, and best QUIC endpoint. Can resolve target by regular agentId or ERC-7857 reference.

Required: latitude, longitude, and either agentId or ERC-7857 reference fields.

GET /v1/routing/anchors

Headers: Authorization: Bearer sk_...

Params: ?lat=37.77&lon=-122.41&resolution=5

Response Schema:

{
  "ok": true,
  "cellId": "85283473fffffff",
  "anchors": [...]
}

6. Examples

A) Register agent with ERC-7857 binding (DID unchanged)

curl -X POST https://opacus.xyz/api/kinetic/mcp/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer opak_your_key" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"kineti_h3_register_agent",
    "params":{
      "name":"Research Agent",
      "latitude":41.0082,
      "longitude":28.9784,
      "capabilities":["oracle","general"],
      "erc7857Contract":"0xYourErc7857Contract",
      "erc7857TokenId":"123",
      "erc7857ChainId":16601
    }
  }'

B) Update location by ERC-7857 reference (no agentId needed)

curl -X POST https://opacus.xyz/api/kinetic/mcp/rpc \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer opak_your_key" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"kineti_h3_location_update",
    "params":{
      "latitude":40.991,
      "longitude":29.027,
      "erc7857Contract":"0xYourErc7857Contract",
      "erc7857TokenId":"123",
      "erc7857ChainId":16601
    }
  }'

C) Legacy DID-only flow (still supported)

Curl Snippet:

curl "https://opacus.xyz/api/v1/routing/anchors?lat=37.77&lon=-122.41&resolution=5"   -H "Authorization: Bearer sk_test"

7. Response Notes

• Successful register/update responses include did and spatial.did.
• When adapter mode is active, response includes erc7857 object with chain/contract/token details.
• DID format is never replaced by NFT fields.

8. Errors

• 400 BAD_REQUEST invalid coordinates or missing required params.
• -32004 ERC-7857 reference already linked to another Opacus account scope.
• -32404 H3/Citadel agent not found during location update.

9. Compatibility Checklist

• Keep DID as source of truth for routing and policy logic.
• Treat ERC-7857 as optional external reference (adapter layer).
• Prefer passing latitude/longitude for precise QUIC endpoint assignment.
• Use explicit agentId when available; use ERC reference for NFT-native flows.

10. Best Practices

Resolution level 5 is a good default for city/metro routing. Avoid very high resolutions unless required by your matching policy. For production, periodically re-run kineti_h3_location_update when your agent infrastructure moves between regions.