REST API Reference

Everything TAG IT exposes over HTTP today. Every endpoint listed without a Planned marker is live and was verified by direct request on 26 July 2026 — you can call it right now, and most of it needs no key at all.

What exists today

TAG IT has two HTTP hosts and one on-chain path. There is no single /v1 base URL — endpoints are grouped by the host that serves them.

Reading state directly from the chain

The most reliable integration path requires no TAG IT credential at all: read the TAGITCore contract yourself over any public Base Sepolia RPC. You do not have to trust our API — you can re-derive every verdict independently.

See Contract Addresses for the full deployment list.

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

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

const TAGITCoreABI = [{
  name: 'getAsset', type: 'function', 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 [owner, timestamp, state] = await client.readContract({
  address: '0x3aDc7EFDb58Ae85483eFf5D4966D916185f31d1D',
  abi: TAGITCoreABI,
  functionName: 'getAsset',
  args: [50n],
});

console.log({ owner, timestamp, state });
// → { owner: '0x458B4d0c3a55006965Fd13D6af7B8509De51Cb3D',
//     timestamp: 1784246184n, state: 4 }   // 4 = CLAIMED

Lifecycle states

The state field is an integer from the asset lifecycle state machine:

GET /health

Gateway liveness check. No authentication.

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

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

POST /verify

Signed verification of an asset's on-chain state, gated by the x402 micropayment protocol. Calling it without a payment proof returns 402 Payment Required together with the payment requirements — that response is the protocol handshake, not an error.

curl -X POST "https://api.tagit.network/verify" \
  -H "Content-Type: application/json" \
  -d '{"assetId":"18","chain":"base-sepolia"}'

Response when no payment proof is attached:

{
  "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",
    "maxTimeoutSeconds": 30
  }]
}

With a valid X-PAYMENT header, the response carries the asset state plus an ECDSA signature over keccak256(tokenId, state, chainId, timestamp), so the verdict can be checked on-chain.

GET /api/verify

Verifies a physical NFC tap. NTAG 424 DNA chips emit an AES-encrypted PICC blob that cannot be decrypted on-device, so the tap's picc and cmac values are verified server-side and resolved to the on-chain twin. Both parameters come from the chip itself — they cannot be constructed without physically tapping it.

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

GET /api/dpp/…

Returns the asset's Digital Product Passport as a W3C Verifiable Credential (VCDM 2.0 JSON-LD, UNTP DigitalProductPassport profile), served as application/ld+json and CORS-open so external verifiers and GS1 resolvers can consume it. Like /api/verify, it requires a SUN cryptogram from a physical tap.

# By GS1 Digital Link identity
curl "https://verify.tagit.network/api/dpp/01/<GTIN>/21/<serial>?picc=<hex>&cmac=<hex>"

# By token ID
curl "https://verify.tagit.network/api/dpp/token/<tokenId>?picc=<hex>&cmac=<hex>"

The credential is unsigned in v1 — integrity comes from the on-chain anchor carried in its evidence field, which any consumer can re-derive from public RPC. The matching human-readable passport renders at verify.tagit.network/01/{GTIN}/21/{serial}. The same host serves an untapped, token-addressed page: check an asset on-chain on verify.tagit.network.

Planned

These are not yet available. They are listed so you can plan against them, and they will be documented here with working examples on the day they ship — not before.

Error codes

Error responses carry a JSON body with an error field describing the failure.

Rate limiting

Public endpoints are rate limited per IP. There are no subscription tiers and no API keys today — if you need a higher limit for an integration, get in touch.