INFT API Reference

These endpoints are live today — backed by the off-chain KV land registry in agent-kernel. They represent Phase 1 of the INFT system. On-chain contracts (Phase 2) will honour the same API surface.

Endpoints

GET /v1/land/check

Check whether a given H3 cell has a registered INFT land owner. Agents and smart contracts call this before executing a task to determine whether a micro-fee will be routed.

Query Parameters

Response — cell owned

{
  "ok": true,
  "h3_index": "853f6287fffffff",
  "land": {
    "owned": true,
    "owner": "0xabc123...",
    "inft_token_id": "42",
    "chain": "0g",
    "micro_fee_bps": 25
  }
}

Response — cell not owned

{
  "ok": true,
  "h3_index": "853f6287fffffff",
  "land": {
    "owned": false
  }
}

Code Examples

const res = await fetch(
  'https://opacus.xyz/api/v1/land/check?h3_index=853f6287fffffff'
);
const data = await res.json();

if (data.land.owned) {
  console.log('Owner:', data.land.owner);
  console.log('Micro-fee:', data.land.micro_fee_bps / 100, '%');
}

curl "https://opacus.xyz/api/v1/land/check?h3_index=853f6287fffffff"

POST /v1/land/register

Register your INFT as the land owner of an H3 cell. Requires proof of INFT ownership (the inft_token_id you hold on 0G chain). One cell can only have one owner — a second registration returns 409 INFT_LAND_FEE_REQUIRED.

After registration, all Opacus tasks originating in this cell begin recording a 0.25 % micro-fee in your favour (queryable via GET /v1/land/fees).

Request Body (JSON)

Success Response

{
  "ok": true,
  "h3_index": "853f6287fffffff",
  "owner": "0xabc123...",
  "inft_token_id": "42",
  "chain": "0g",
  "message": "iNFT land registered for H3 cell 853f6287fffffff"
}

Error Codes

Code Examples

const res = await fetch('https://opacus.xyz/api/v1/land/register', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    h3_index: '853f6287fffffff',  // Aydın MetroCell
    inft_token_id: '42',
  }),
});

const data = await res.json();
// { ok: true, h3_index: "853f6287fffffff", owner: "0x...", ... }
console.log('Registered:', data.h3_index);

curl -X POST https://opacus.xyz/api/v1/land/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"h3_index":"853f6287fffffff","inft_token_id":"42"}'

import httpx

r = httpx.post(
    "https://opacus.xyz/api/v1/land/register",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"h3_index": "853f6287fffffff", "inft_token_id": "42"},
)
r.raise_for_status()
print(r.json())  # {"ok": True, "h3_index": "853f6287fffffff", ...}

GET /v1/land/fees

Returns the total accumulated micro-fees (0.25 % of all tasks in your cells) and the last 100 individual fee events. Phase 2 on-chain settlement will replace this with direct USDC transfers.

Response

{
  "ok": true,
  "total_micro_fees": 0.04215,
  "transaction_count": 183,
  "fees": [
    {
      "h3Index": "853f6287fffffff",
      "owner": "0xabc123...",
      "inftTokenId": "42",
      "agentWallet": "0xdef456...",
      "txAmount": 0.01,
      "feeAmount": 0.000025,
      "ts": 1714297600000
    }
    // ... up to 100 most recent
  ]
}

Code Examples

const res = await fetch('https://opacus.xyz/api/v1/land/fees', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
});
const { total_micro_fees, transaction_count, fees } = await res.json();
console.log(`Earned: $${total_micro_fees} USDC across ${transaction_count} tasks`);

curl https://opacus.xyz/api/v1/land/fees \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /v1/land/map

Returns all registered H3 land cells with their owners. Useful for building map visualisations of INFT coverage.

Query Parameters

Response

{
  "ok": true,
  "count": 12,
  "cells": [
    {
      "h3_index": "853f6287fffffff",
      "owner": "0xabc123...",
      "inft_token_id": "42",
      "chain": "0g",
      "registered_at": "2026-04-01T10:30:00.000Z"
    }
  ]
}

How the Micro-Fee Works (Phase 1)

Every time an agent executes a task on Opacus, agent-kernel calls _checkLandOwner(h3Index). If the cell has a registered owner, a 0.25 % micro-fee entry is written to the KV store via _recordLandMicroFee().

The fee is accrued off-chain in Phase 1 — no on-chain transfer happens yet. Phase 2 replaces this with RentRouter.sol handling live USDC transfers.

Finding Your H3 Cell Index

Use the Opacus SDK to convert GPS coordinates to an H3 cell:

import { latLngToH3Cell } from 'opacus-sdk/h3';

// Istanbul city centre → Res-5 MetroCell
const h3 = latLngToH3Cell(41.0082, 28.9784, 5);
console.log(h3); // e.g. "853f3477fffffff"

// Or use the Opacus dashboard H3 calculator at /dashboard

Or use the interactive H3 calculator in the Opacus Dashboard (bottom of the node tools section).

Related Pages

• INFT Overview — what INFTs are, tier system, economics
• H3 System — cell resolution reference
• Bootstrap & Tokens — get an API key