First Integration

This guide builds a working integration against what TAG IT actually runs today: a direct on-chain read of asset lifecycle state, plus the live verification endpoints. Every code sample and every response on this page was executed against the live network before publication.

What Works Today

Docs that describe features ahead of implementation waste your time. So here is the honest inventory. Everything marked Live below was exercised on 2026-07-26 and is documented in this guide; everything marked Not available is covered in the last section.

Step 1: Read an Asset On-Chain

The blockchain record is the source of truth, and it is public. You do not need TAG IT's permission, an account, or an API key to read it — you need a Base Sepolia RPC endpoint and an ABI fragment. This is the foundation of every integration below.

Install the only dependency:

npm install viem

Then read the asset:

import { createPublicClient, http } from 'viem';
import { baseSepolia } from 'viem/chains';

// TAGITCore on Base Sepolia (chain ID 84532)
const TAGIT_CORE = '0x3aDc7EFDb58Ae85483eFf5D4966D916185f31d1D';

const tagitCoreAbi = [
  {
    type: 'function',
    name: 'getAsset',
    stateMutability: 'view',
    inputs: [{ name: 'tokenId', type: 'uint256' }],
    outputs: [
      { name: 'assetOwner', type: 'address' },
      { name: 'timestamp',  type: 'uint64'  },
      { name: 'state',      type: 'uint8'   },
      { name: 'flags',      type: 'uint8'   },
      { name: 'reserved',   type: 'uint16'  }
    ]
  }
];

const STATE_NAMES = [
  'NONE', 'MINTED', 'BOUND', 'ACTIVATED', 'CLAIMED', 'FLAGGED', 'RECYCLED'
];

const client = createPublicClient({
  chain: baseSepolia,
  transport: http()
});

async function readAsset(tokenId) {
  const [assetOwner, timestamp, state, flags, reserved] = await client.readContract({
    address: TAGIT_CORE,
    abi: tagitCoreAbi,
    functionName: 'getAsset',
    args: [BigInt(tokenId)]
  });

  return {
    tokenId,
    owner: assetOwner,
    state,
    stateName: STATE_NAMES[state] ?? 'UNKNOWN',
    lastStateChange: new Date(Number(timestamp) * 1000).toISOString(),
    flags,
    reserved
  };
}

console.log(await readAsset(50));

Token ID 50 exists on Base Sepolia right now, so you can run the above unchanged. It prints:

{
  tokenId: 50,
  owner: '0x458B4d0c3a55006965Fd13D6af7B8509De51Cb3D',
  state: 4,
  stateName: 'CLAIMED',
  lastStateChange: '2026-07-16T23:56:24.000Z',
  flags: 0,
  reserved: 0
}

The five returned fields are the packed on-chain asset record:

• assetOwner — the current on-chain owner address.
• timestamp — Unix seconds of the last state change, not the mint date.
• state — the lifecycle state, 0–6 (table below).
• flags — a bit field reserved for future use; currently 0.
• reserved — reserved for future metadata; currently 0.

A token ID that has never been minted does not revert. It returns the zero record: owner 0x0000…0000 and state 0 (NONE). Handle that case explicitly — see Handling Results.

Lifecycle States

Every asset moves through a seven-state machine. The state value returned above maps to:

Step 2: The Verification API

Two endpoints on api.tagit.network are live. Start with the health check, which needs no authentication:

curl https://api.tagit.network/health

Actual response:

{"status":"ok","timestamp":"2026-07-26T21:53:19.795Z","runtime":"vercel"}

The verification endpoint is metered using the x402 payment protocol. Called without a payment header, it returns HTTP 402 and an envelope describing what payment it will accept:

curl -X POST https://api.tagit.network/verify \
  -H 'content-type: application/json' \
  -d '{}'

Actual response (HTTP 402):

{
  "x402Version": 1,
  "error": "Payment required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "10000",
      "resource": "https://api.tagit.network/verify",
      "description": "TAG IT Asset Verification — BOUND state proof + ECDSA signature",
      "mimeType": "application/json",
      "payTo": "0x458B4d0c3a55006965Fd13D6af7B8509De51Cb3D",
      "maxTimeoutSeconds": 30,
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
    }
  ]
}

That 402 envelope is the endpoint's real, current contract with clients: an x402-capable client reads accepts, settles the payment on Base Sepolia, and retries with a payment header. The shape of the settled success response is not documented here because it is not yet stable — treat it as subject to change and do not hard-code against it. If all you need is the owner and lifecycle state, the on-chain read in Step 1 gives you that for free and with no payment flow at all.

Step 3: Verifying a Physical Tag

Step 1 tells you about a token ID. It cannot tell you whether the object in someone's hand is the real one. Only a physical NFC tap can do that, because only the chip can produce a fresh cryptographic message authentication code.

When an NTAG 424 DNA tag is tapped, the chip's Secure Dynamic Messaging mirror appends two values to the URL it emits: an encrypted PICC data blob and a CMAC. The verification service checks them:

curl "https://verify.tagit.network/api/verify?picc=<32-hex-chars>&cmac=<16-hex-chars>"

The same tap can be resolved as a W3C Verifiable Credential digital product passport, keyed by GS1 GTIN and serial:

curl "https://verify.tagit.network/api/dpp/01/<GTIN>/21/<serial>?picc=<32-hex-chars>&cmac=<16-hex-chars>"

For flows where you want to hand a person a link rather than parse JSON, the following pages on verify.tagit.network render a verification result directly — for example, check asset 50 on-chain:

• https://verify.tagit.network/asset/<tokenId>
• https://verify.tagit.network/tag/<uid>
• https://verify.tagit.network/01/<gtin>/21/<serial>

Handling Results

Your UI needs to handle every state the contract can return, including the zero record. This continues from Step 1 and reuses readAsset():

async function checkAsset(tokenId) {
  const asset = await readAsset(tokenId);

  switch (asset.state) {
    case 0: // NONE
      return {
        display: 'not-found',
        headline: 'No record for this token ID',
        detail: 'This token has never been minted on TAGITCore. A zero record is also '
              + 'what you get if you query the wrong contract or the wrong chain.'
      };

    case 1: // MINTED
    case 2: // BOUND
    case 3: // ACTIVATED
      return {
        display: 'in-production',
        headline: `Asset exists — ${asset.stateName}`,
        detail: 'The digital twin exists but has not been claimed by an end owner yet.'
      };

    case 4: // CLAIMED
      return {
        display: 'claimed',
        headline: 'Claimed by an owner',
        detail: `On-chain owner ${asset.owner}, last state change ${asset.lastStateChange}.`
      };

    case 5: // FLAGGED
      return {
        display: 'flagged',
        headline: 'Flagged',
        detail: 'This asset is under a lost, stolen or recall investigation.'
      };

    case 6: // RECYCLED
      return {
        display: 'recycled',
        headline: 'Recycled',
        detail: 'End of life. This is a terminal state.'
      };

    default:
      return {
        display: 'unknown',
        headline: 'Unrecognised state',
        detail: `Contract returned state ${asset.state}.`
      };
  }
}

Not Available Yet

These are things developers reasonably expect and that TAG IT does not have today. Nothing below is a preview of an imminent release; treat it as a list of things you must design around.

Next Steps

• Contract Addresses — deployed addresses and chain IDs
• ABI Reference — the full contract interface, beyond getAsset()
• Platform Overview — how the pieces fit together
• NFC Chip Selection — why NTAG 424 DNA, and what tap verification requires