Build

TypeScript SDK

The TAG IT TypeScript SDK is an ERC-8004 agent client. It wraps the on-chain agent registries — identity, reputation, validation and staking — in typed viem clients, and ships event watchers for the same contracts. Without a private key it runs fully read-only — no account, no API key.

Scope is worth stating plainly: the SDK covers the agent layer (identity, reputation, validation, staking), A2A, and TAGITCore reads plus capability-gated writes (mint, bindTag, activate, claim, flag, approveResolve). It does not verify NFC taps — that is the services API. For those, read and write TAGITCore directly — see Reading asset state below.

Supported today: TypeScript / JavaScript. Python, iOS, and Android SDKs: planned, not yet available.

Installation — build from source

There is no published package, so clone the repository and build it. The build emits dist/:

git clone https://github.com/TAG-IT-NETWORK/tagit-sdk.git
cd tagit-sdk
npm install
npm run build

Then link the build into your project. npm link is what makes the @tagitnetwork/sdk import specifier used in the examples below resolve — it is the package's own name in package.json, not a registry lookup:

# in the tagit-sdk checkout
npm link

# in your project
npm link @tagitnetwork/sdk

Quick start — createAgentClient

createAgentClient(config) returns a client with identity, reputation, validation, staking, and events namespaces. Pass baseSepolia explicitly: the SDK still defaults to OP Sepolia (chainId 11155420), which was deprecated on 2026-06-27 in favour of Base Sepolia (chainId 84532). It resolves the deployed contract addresses from whichever chain id you give it.

import { createAgentClient } from "@tagitnetwork/sdk";
import { baseSepolia } from "viem/chains";

// Read-only client — no private key needed
const client = createAgentClient({
  chain: baseSepolia,
  rpcUrl: "https://sepolia.base.org",
});

// Agent identity
const agent = await client.identity.getAgent(1n);
console.log(agent.wallet, agent.active);

// On-chain reputation
const reputation = await client.reputation.getSummary(1n);
console.log(reputation.averageRating);

// Validation status
const status = await client.validation.getValidationStatus(1n);
console.log(status.isValidated);

Providing a privateKey in the config enables the write methods — identity.register, reputation.giveFeedback, validation.validationRequest, and the rest — each returning the transaction hash. The events namespace exposes watchers such as watchAgentRegistered and watchFeedbackGiven that return an unsubscribe function.

What the gateway at api.tagit.network serves

Two endpoints, and it is worth being exact about them. GET /health returns a small JSON status document. POST /verify answers with an x402 payment envelope (HTTP 402) stating what the call costs before it will run.

curl -s https://api.tagit.network/health
# {"status":"ok","timestamp":"2026-10-23T18:31:29.397Z","agents":{"count":6,"details":[...]}}

The SDK ships an A2A client under the @tagitnetwork/sdk/a2a subpath. Since 2026-09-14 the gateway publishes an agent card at GET https://api.tagit.network/.well-known/agent.json (public) and accepts POST /a2a tasks with an API key (401 without one; probed 2026-10-23). Whether this SDK build talks to it end to end has not been exercised from outside. Reading agent identity, reputation and validation needs no key at all — the quick start above does it straight from the contracts.

Reading asset state

A product's digital twin lives in TAGITCore on Base Sepolia. getAsset(tokenId) returns the owner, the timestamp of the last state change, and the current lifecycle state (0 NONE → 6 RECYCLED — see Asset Lifecycle).

Via the SDK

The SDK exports the deployed addresses per chain; combine getAddresses with a viem public client:

import { getAddresses } from "@tagitnetwork/sdk";
import { createPublicClient, http, parseAbi } from "viem";
import { baseSepolia } from "viem/chains";

const { TAGITCore } = getAddresses(baseSepolia.id); // 84532

const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http("https://sepolia.base.org"),
});

const coreAbi = parseAbi([
  "function getAsset(uint256 tokenId) view returns (address assetOwner, uint64 timestamp, uint8 state, uint8 flags, uint16 reserved)",
]);

const [owner, timestamp, state] = await publicClient.readContract({
  address: TAGITCore,
  abi: coreAbi,
  functionName: "getAsset",
  args: [1n],
});

const STATES = [
  "NONE", "MINTED", "BOUND", "ACTIVATED",
  "CLAIMED", "FLAGGED", "RECYCLED",
];
console.log(owner, STATES[state]);

Plain viem — no SDK

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

const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http("https://sepolia.base.org"),
});

const [owner, , state] = await publicClient.readContract({
  // TAGITCore proxy on Base Sepolia
  address: "0x3aDc7EFDb58Ae85483eFf5D4966D916185f31d1D",
  abi: parseAbi([
    "function getAsset(uint256 tokenId) view returns (address assetOwner, uint64 timestamp, uint8 state, uint8 flags, uint16 reserved)",
  ]),
  functionName: "getAsset",
  args: [1n],
});

The same read works with ethers or any EVM library — it is a plain view call against a verified contract on sepolia.basescan.org.

Querying the Goldsky subgraph

The deployed tagit-indexer subgraph indexes the ERC-8004 agent layer into a GraphQL API. Its query root is exactly: protocol, agent, agentMetadata, agentStatusChange, feedback, validationRequest, validationResponse (each with its plural collection). Asset lifecycle entities are defined in the tagit-indexer repository but are not deployed at this endpoint — indexing them is planned, not yet available. For lifecycle state, read TAGITCore directly as shown above.

Agents with reputation and validation state

curl -s https://api.goldsky.com/api/public/project_cmk3631vfave701vphm5ted0l/subgraphs/tagit-indexer/0.2.0/gn \
  -H "Content-Type: application/json" \
  -d '{"query": "{ agents(first: 5) { agentId wallet statusLabel averageRating feedbackCount isValidated } }"}'

Protocol totals and recent feedback

{
  protocols(first: 1) {
    totalAgents
    totalActiveAgents
    totalFeedback
    averageRating
    totalValidationRequests
  }
  feedbacks(first: 5, orderBy: createdAt, orderDirection: desc) {
    feedbackId
    agent { agentId }
    reviewer
    rating
    revoked
    createdAt
  }
}

CLI

The repository ships a tagit binary for agent reads and registrations from the terminal. There is no global install to run — it comes from the same source build, and npm link in the checkout puts tagit on your PATH:

# Agent info (read-only)
tagit agent info --agent-id 1 --json

# Register an agent (write — needs a funded testnet key)
tagit agent register --wallet 0x... --uri ipfs://... --private-key 0x...

Next steps

• Agent API — what is live at api.tagit.network: GET /health and the x402-priced POST /verify
• Asset Lifecycle — what each state value means and which transitions are legal
• Contract Addresses — the full Base Sepolia deployment registry