Integrator Guide

This comprehensive guide covers everything an integrator (marketplace, venue, or platform) needs to know to build on TIX Protocol.

What is an Integrator?

An integrator is a third-party platform that uses TIX Protocol for ticketing operations:

• Ticketing marketplaces — Primary and secondary ticket sales

• Event organizers — Direct-to-consumer ticket issuance

• Venue box offices — On-site ticket operations

• Fan clubs — Exclusive access and ticket distribution

Getting Registered

Registration Process

1. Contact Protocol Operator — Request integrator registration

2. Provide Authority Key — Your signing authority public key

3. Co-sign Registration — Both parties sign the registration transaction

4. Receive Integrator Account — PDA created with your identity

Registration Transaction

import { registerIntegrator } from "@tixprotocol/sdk";

const { tx, integrator, treasury } = await registerIntegrator({
  connection,
  payer: protocolOperator.publicKey,
  protocolAuthority: protocolOperator.publicKey,
  integratorIdentity: yourIdentityKeypair.publicKey,
  integratorAuthority: yourAuthorityKeypair.publicKey,
});

// Both must sign
tx.sign([protocolOperator, yourIdentityKeypair, yourAuthorityKeypair]);
await connection.sendTransaction(tx);

console.log(`Integrator PDA: ${integrator.toBase58()}`);
console.log(`Treasury ATA: ${treasury.toBase58()}`);

Fund Your Treasury

Your treasury must have USDC to pay protocol fees:

// Minimum recommended balance
const recommendedBalance = 1000_000_000n; // $1,000 USDC

// Check current balance
const balance = await connection.getTokenAccountBalance(treasuryAta);
console.log(`Treasury balance: ${balance.value} USDC`);

Managing Events

Create an Event

import { registerEvent } from "@tixprotocol/sdk";

const { tx, event } = await registerEvent({
  connection,
  payer: integratorAuthority.publicKey,
  integratorIdentity: integratorIdentity.publicKey,
  integratorAuthority: integratorAuthority.publicKey,
  eventId: 2001n,
  totalSupply: 10000n,
  royaltyBps: 500, // 5%
  minRoyaltyFloor: 100_000n, // $1.00 minimum
  royaltyRecipients: [
    { destination: artistAta, bps: 300 },
    { destination: venueAta, bps: 200 },
  ],
});

tx.sign([integratorAuthority]);
await connection.sendTransaction(tx);

Event Planning Checklist

Step	Action
1	Define total ticket supply
2	Set royalty percentage and floor
3	Create USDC ATAs for royalty recipients
4	Calculate BPS splits (must sum to royaltyBps)
5	Choose unique event ID
6	Register event on-chain

Query Event State

import { getEvent, eventPda } from "@tixprotocol/sdk";

const eventPubkey = eventPda(eventId);
const eventState = await getEvent(connection, eventPubkey);

console.log(`Event ID: ${eventId}`);
console.log(`Total Supply: ${eventState.totalSupply}`);
console.log(`Minted: ${eventState.minted}`);
console.log(`Remaining: ${eventState.totalSupply - eventState.minted}`);

Issuing Tickets

Batch Issuance

import { issuePermits } from "@tixprotocol/sdk";

const customers = [
  customer1.publicKey,
  customer2.publicKey,
  customer3.publicKey,
  // ... more customers
];

const tx = await issuePermits({
  connection,
  payer: integratorAuthority.publicKey,
  integratorIdentity: integratorIdentity.publicKey,
  integratorAuthority: integratorAuthority.publicKey,
  eventId: 2001n,
  buyers: customers,
});

tx.sign([integratorAuthority]);
await connection.sendTransaction(tx);

Ticket ID Management

// Track issued ticket IDs
let nextTicketId = 0n;

async function issueNextTicket(buyer: PublicKey) {
  const tx = await issuePermit({
    // ... params
    ticketId: nextTicketId,
  });

  tx.sign([integratorAuthority]);
  await connection.sendTransaction(tx);

  nextTicketId++;
  return nextTicketId - 1n; // Return issued ticket ID
}

Facilitating Transfers

Integrator-Initiated Transfer

As an integrator, you can transfer tickets on behalf of holders:

import { transferPermit } from "@tixprotocol/sdk";

const tx = await transferPermit({
  connection,
  payer: integratorAuthority.publicKey,
  eventId: 2001n,
  ticketId: 42n,
  currentOwner: originalOwner.publicKey,
  newOwner: newOwner.publicKey,
  integratorIdentity: integratorIdentity.publicKey,
  signer: integratorAuthority.publicKey, // You sign instead of owner
});

tx.sign([integratorAuthority]);
await connection.sendTransaction(tx);

When to Use Integrator Transfer

Scenario	Use Integrator Transfer?
User requests transfer in your app	✅ Yes
Bulk transfers during migration	✅ Yes
Correcting issuance errors	✅ Yes
Transferring without user consent	❌ No (policy decision)

Ticket Lifecycle Management

Mark Ticket as Used (Redemption)

When a fan enters the venue:

import { markUsed } from "@tixprotocol/sdk";

const tx = await markUsed({
  connection,
  payer: integratorAuthority.publicKey,
  eventId: 2001n,
  ticketId: 42n,
  integratorIdentity: integratorIdentity.publicKey,
  integratorAuthority: integratorAuthority.publicKey,
});

tx.sign([integratorAuthority]);
await connection.sendTransaction(tx);

Mark Ticket as Void (Cancellation)

For refunds or chargebacks:

import { markVoid } from "@tixprotocol/sdk";

const tx = await markVoid({
  connection,
  payer: integratorAuthority.publicKey,
  eventId: 2001n,
  ticketId: 42n,
  integratorIdentity: integratorIdentity.publicKey,
  integratorAuthority: integratorAuthority.publicKey,
});

tx.sign([integratorAuthority]);
await connection.sendTransaction(tx);

Listing Management

Cancel Listings

Integrators can cancel any listing for their events:

import { cancelListing } from "@tixprotocol/sdk";

const tx = await cancelListing({
  connection,
  payer: integratorAuthority.publicKey,
  eventId: 2001n,
  ticketId: 42n,
  authority: integratorAuthority.publicKey,
});

tx.sign([integratorAuthority]);
await connection.sendTransaction(tx);

When to Cancel Listings

Reason	Action
Event cancelled	Cancel all listings
Suspicious activity	Cancel fraudulent listings
Policy violation	Cancel violating listings
Price cap exceeded	Cancel overpriced listings
User request	Help user cancel

Authority Management

Update Your Authority Key

If you need to rotate keys:

import { updateIntegratorAuthority } from "@tixprotocol/sdk";

const tx = await updateIntegratorAuthority({
  connection,
  payer: currentAuthority.publicKey,
  integratorIdentity: integratorIdentity.publicKey,
  currentAuthority: currentAuthority.publicKey,
  newAuthority: newAuthority.publicKey,
});

tx.sign([currentAuthority]);
await connection.sendTransaction(tx);

Key Security Best Practices

Practice	Description
HSM Storage	Store authority keys in hardware security modules
MPC Wallets	Use multi-party computation for signing
Key Rotation	Regularly rotate authority keys
Audit Logging	Log all authority operations
Access Control	Limit who can access authority keys

Monitoring & Analytics

Query Your Integrator State

import { getIntegrator, integratorPda } from "@tixprotocol/sdk";

const integratorPubkey = integratorPda(integratorIdentity);
const state = await getIntegrator(connection, integratorPubkey);

console.log(`Status: ${state.status}`);
console.log(`Authority: ${state.authority.toBase58()}`);
console.log(`Treasury: ${state.treasuryUsdc.toBase58()}`);

Monitor Treasury Balance

async function checkTreasuryHealth() {
  const balance = await connection.getTokenAccountBalance(treasuryAta);
  const minBalance = 100_000_000n; // $100 minimum

  if (balance.value < Number(minBalance) / 1_000_000) {
    console.warn("Treasury balance low! Please fund.");
    // Send alert to operations team
  }
}

Track Event Metrics

async function getEventMetrics(eventId: bigint) {
  const eventPubkey = eventPda(eventId);
  const event = await getEvent(connection, eventPubkey);

  return {
    totalSupply: event.totalSupply,
    minted: event.minted,
    remaining: event.totalSupply - event.minted,
    percentageSold: (Number(event.minted) / Number(event.totalSupply)) * 100,
  };
}

Integration Patterns

Webhook-Based Integration

// When user completes checkout
async function onCheckoutComplete(order: Order) {
  const tx = await issuePermit({
    connection,
    payer: integratorAuthority.publicKey,
    integratorIdentity: integratorIdentity.publicKey,
    integratorAuthority: integratorAuthority.publicKey,
    eventId: order.eventId,
    buyer: new PublicKey(order.walletAddress),
    ticketId: order.ticketId,
  });

  tx.sign([integratorAuthority]);
  const sig = await connection.sendTransaction(tx);

  // Update order with transaction signature
  await updateOrder(order.id, { txSignature: sig });
}

Troubleshooting

Common Issues

Issue	Cause	Solution
IntegratorSuspended	Your integrator is suspended	Contact protocol operator
InsufficientFunds	Treasury lacks USDC	Fund your treasury
Unauthorized	Wrong authority key	Use correct signing key
SupplyExceeded	Event sold out	Check remaining supply
Transaction timeout	Network congestion	Retry with priority fee

Debug Checklist

1. Is integrator status Active?

2. Is treasury funded sufficiently?

3. Are you using the correct authority key?

4. Is the event ID correct?

5. Is the ticket ID within supply bounds?

6. Is the permit in the correct status?

Next Steps

• SDK Reference — Complete SDK documentation

• API Reference — All available instructions

• Error Codes — Error handling guide