@gtcx/sdk

Official TypeScript SDK for GTCX Protocol.

Installation

npm install @gtcx/sdk
# or
pnpm add @gtcx/sdk
# or
yarn add @gtcx/sdk

Quick Start

import { GTCXClient } from '@gtcx/sdk';

// Initialize client
const client = new GTCXClient({
  apiUrl: 'https://api.testnet.gtcx.io',
  networkId: 'gtcx:testnet',
  chainId: 'gtcx-testnet-1',
  apiKey: process.env.GTCX_API_KEY,
});

// Verify a TradePass credential
const credential = await client.tradepass.resolve('did:gtcx:tp_producer_001');
const verification = await client.tradepass.verify(credential);

console.log(`Valid: ${verification.valid}`);

Features

• Full TypeScript Support: Complete type definitions with Zod runtime validation
• All Protocol Components: TradePass, GCI, GeoTag, VaultMark, Settlement
• Tree-Shakable: Import only what you need
• Zero Dependencies: Only Zod for runtime validation

API Reference

GTCXClient

Main client for interacting with GTCX Protocol.

const client = new GTCXClient({
  apiUrl: string;      // API endpoint
  networkId: string;   // Network identifier
  chainId: string;     // Chain ID
  apiKey?: string;     // Optional API key
  timeout?: number;    // Request timeout (default: 30000ms)
});

TradePass

Digital identity and credential management.

// Resolve a DID to credential
const credential = await client.tradepass.resolve('did:gtcx:tp_...');

// Verify a credential
const result = await client.tradepass.verify(credential);

// Issue a new credential (requires issuer permissions)
const newCredential = await client.tradepass.issue({
  did: 'did:gtcx:tp_new_producer',
  name: 'Kwame Asante',
  role: 'producer',
  entityId: 'entity_001',
  jurisdiction: 'GH',
});

// Revoke a credential
await client.tradepass.revoke('did:gtcx:tp_...', 'License expired');

GCI (Global Compliance Index)

Compliance scoring and management.

// Get current score
const score = await client.gci.getScore('entity_001');
console.log(`Score: ${score.score}/100 (${score.tier})`);

// Get score history
const history = await client.gci.getHistory('entity_001', 30);

// Get improvement suggestions
const suggestions = await client.gci.getSuggestions('entity_001');

// Submit evidence for a factor
await client.gci.submitEvidence('entity_001', 'documentation', ['https://example.com/license.pdf']);

GeoTag

Location verification.

// Submit a location claim
const claim = await client.geotag.submit({
  type: 'extraction',
  location: {
    latitude: 6.6885,
    longitude: -1.6244,
    accuracy: 5,
    timestamp: new Date().toISOString(),
    source: 'gps',
  },
  claimant: 'did:gtcx:tp_producer_001',
  licenseId: 'GH-ML-2024-001234',
});

// Verify a claim
const verification = await client.geotag.verify(claim.id);
console.log(`Within boundary: ${verification.withinBoundary}`);

VaultMark

Custody tracking and management.

// Get custody status
const custody = await client.vaultmark.getCustody('lot:gh-ash-20260120-001');

// Get custody history
const history = await client.vaultmark.getHistory('lot:gh-ash-20260120-001');

// Transfer custody
const newCustody = await client.vaultmark.transfer(
  'lot:gh-ash-20260120-001',
  'did:gtcx:tp_vault_001'
);

// Transfer with escrow
const escrowCustody = await client.vaultmark.transfer(
  'lot:gh-ash-20260120-001',
  'did:gtcx:tp_buyer_001',
  {
    escrow: true,
    releaseConditions: ['payment_confirmed', 'inspection_passed'],
  }
);

// Split a lot
const [lot1, lot2] = await client.vaultmark.split('lot:gh-ash-20260120-001', [1.5, 1.0]);

// Merge lots
const mergedLot = await client.vaultmark.merge([
  'lot:gh-ash-20260120-001',
  'lot:gh-ash-20260120-002',
]);

Settlement

Payment-versus-Physical settlement.

// Create settlement
const settlement = await client.settlement.create({
  lotId: 'lot:gh-ash-20260120-001',
  buyer: 'did:gtcx:tp_buyer_001',
  seller: 'did:gtcx:tp_producer_001',
  amount: { value: 125000, currency: 'USD' },
  paymentMethod: 'escrow',
});

// Confirm payment
await client.settlement.confirmPayment(settlement.id, 'tx_proof_123');

// Confirm delivery
await client.settlement.confirmDelivery(settlement.id, 'delivery_proof_456');

// Dispute if needed
await client.settlement.dispute(settlement.id, 'Weight mismatch');

Types

All types are exported and can be used for type safety:

import type {
  TradePassCredential,
  TradePassDID,
  TradePassRole,
  GCIScore,
  GCITier,
  GCIFactor,
  GeoTagClaim,
  GeoLocation,
  CustodyRecord,
  CustodyEvent,
  Asset,
  Settlement,
} from '@gtcx/sdk';

Zod Schemas

Runtime validation schemas are also exported:

import {
  TradePassCredentialSchema,
  GCIScoreSchema,
  GeoTagClaimSchema,
  CustodyRecordSchema,
  SettlementSchema,
} from '@gtcx/sdk';

// Validate external data
const result = TradePassCredentialSchema.safeParse(externalData);
if (result.success) {
  // Type-safe credential
  const credential = result.data;
}

Error Handling

import { GTCXClient, GTCXError } from '@gtcx/sdk';

try {
  const credential = await client.tradepass.resolve('did:gtcx:tp_invalid');
} catch (error) {
  if (error instanceof GTCXError) {
    console.log(`Status: ${error.status}`);
    console.log(`Code: ${error.code}`);
    console.log(`Message: ${error.message}`);
  }
}

Networks

| Network | API URL | Description | | ------- | ----------------------------- | ------------------------------ | | Testnet | https://api.testnet.gtcx.io | Development and testing | | Ghana | https://api.ghana.gtcx.io | Ghana pilot network | | Mainnet | https://api.gtcx.io | Production (not yet available) |

License

BSL 1.1 - See LICENSE for details.

Converts to Apache 2.0 on January 1, 2030.

Links

• Documentation
• Protocol Specification
• API Reference
• Discord