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

Contact Protocol Operator — Request integrator registration
Provide Authority Key — Your signing authority public key
Co-sign Registration — Both parties sign the registration transaction
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

Define total ticket supply

Set royalty percentage and floor

Create USDC ATAs for royalty recipients

Calculate BPS splits (must sum to royaltyBps)

Choose unique event ID

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

Controlling Transfers & Resale

TIX Protocol provides integrators with fine-grained control over ticket transfers and secondary market activity. These settings are configured at the event level.

Resale Price Caps

Prevent ticket scalping by setting a maximum resale price for your events. When a price cap is set, any listing exceeding the cap will be rejected by the protocol.

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

const { tx, event } = await registerEvent({
  connection,
  payer: integratorAuthority.publicKey,
  integratorIdentity: integratorIdentity.publicKey,
  integratorAuthority: integratorAuthority.publicKey,
  eventId: 3001n,
  totalSupply: 5000n,
  royaltyBps: 500,
  minRoyaltyFloor: 100_000n,
  royaltyRecipients: [
    { destination: artistAta, bps: 300 },
    { destination: venueAta, bps: 200 },
  ],
  // Set maximum resale price (in USDC minor units)
  resalePriceCap: 200_000_000n, // $200 max resale price
});

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

Price Cap Enforcement

Scenario

Listing Attempt

Result

Price within cap

$150 (cap is $200)

✅ Listing created

Price exceeds cap

$250 (cap is $200)

❌ ResalePriceExceedsCap error

No cap set

Any price

✅ Listing created

Use Cases for Price Caps

Use Case

Recommended Cap

Community events

100-120% of face value

Charity events

Face value only (100%)

Premium events

No cap (market-driven)

General admission

150-200% of face value

Disabling Transfers

For events where tickets should be non-transferable (e.g., identity-verified events), you can disable peer-to-peer transfers entirely.

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

const { tx, event } = await registerEvent({
  connection,
  payer: integratorAuthority.publicKey,
  integratorIdentity: integratorIdentity.publicKey,
  integratorAuthority: integratorAuthority.publicKey,
  eventId: 3002n,
  totalSupply: 1000n,
  royaltyBps: 500,
  minRoyaltyFloor: 100_000n,
  royaltyRecipients: [{ destination: artistAta, bps: 500 }],
  // Disable peer-to-peer transfers
  transfersEnabled: false,
});

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

What Happens When Transfers Are Disabled

transferPermit calls fail — Returns TransfersDisabled error
Integrator transfers still work — Integrator authority can still transfer tickets for customer service purposes
Listings still possible — Unless resale is also disabled (see below)

┌─────────────────────────────────────────────────────────────┐
│           TRANSFERS DISABLED FLOW                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Owner attempts transfer                                    │
│       │                                                     │
│       ▼                                                     │
│  Protocol checks event.transfers_enabled                    │
│       │                                                     │
│       ├── true  → Proceed with transfer                     │
│       │                                                     │
│       └── false → Check if signer is integrator authority   │
│                   │                                         │
│                   ├── Yes → Allow (customer service)        │
│                   └── No  → Reject (TransfersDisabled)      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Use Cases for Disabling Transfers

Scenario

Reason

Identity-verified events

Ticket must match ID at entry

Corporate events

Employees only

VIP experiences

Prevent unauthorized access

Promotional giveaways

Ensure original recipient attends

Disabling Resale

Completely block secondary market listings for an event. This is more restrictive than price caps and prevents any resale activity.

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

const { tx, event } = await registerEvent({
  connection,
  payer: integratorAuthority.publicKey,
  integratorIdentity: integratorIdentity.publicKey,
  integratorAuthority: integratorAuthority.publicKey,
  eventId: 3003n,
  totalSupply: 500n,
  royaltyBps: 0, // No royalties needed if no resale
  minRoyaltyFloor: 0n,
  royaltyRecipients: [],
  // Disable all secondary market activity
  resaleEnabled: false,
});

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

What Happens When Resale Is Disabled

listTicket calls fail — Returns ResaleDisabled error
No secondary market activity — Tickets cannot be listed for sale
Direct transfers may still work — Unless transfersEnabled is also false

Configuration

Transfers

Resale Listings

Default (both enabled)

✅ Allowed

resaleEnabled: false

✅ Allowed

❌ Blocked

transfersEnabled: false

❌ Blocked (owner)

✅ Allowed

Both disabled

❌ Blocked (owner)

❌ Blocked

Combining Restrictions

You can combine multiple restrictions for maximum control:

const { tx, event } = await registerEvent({
  connection,
  payer: integratorAuthority.publicKey,
  integratorIdentity: integratorIdentity.publicKey,
  integratorAuthority: integratorAuthority.publicKey,
  eventId: 3004n,
  totalSupply: 200n,
  royaltyBps: 500,
  minRoyaltyFloor: 100_000n,
  royaltyRecipients: [{ destination: artistAta, bps: 500 }],
  // Fully locked tickets
  transfersEnabled: false,
  resaleEnabled: false,
  // Or capped resale with transfers
  // transfersEnabled: true,
  // resaleEnabled: true,
  // resalePriceCap: 150_000_000n,
});

Updating Event Settings

If you need to modify transfer/resale settings after event creation:

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

const tx = await updateEvent({
  connection,
  payer: integratorAuthority.publicKey,
  integratorIdentity: integratorIdentity.publicKey,
  integratorAuthority: integratorAuthority.publicKey,
  eventId: 3001n,
  // Update specific settings
  resalePriceCap: 250_000_000n, // Raise cap to $250
  // Or enable/disable features
  // resaleEnabled: true,
  // transfersEnabled: true,
});

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

Note: Changing settings does not affect existing listings. Cancel active listings before tightening restrictions.

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

Is integrator status Active?
Is treasury funded sufficiently?
Are you using the correct authority key?
Is the event ID correct?
Is the ticket ID within supply bounds?
Is the permit in the correct status?

Next Steps

SDK Reference — Complete SDK documentation
API Reference — All available instructions
Error Codes — Error handling guide

PreviousSecondary Marketplace NextInstallation

Last updated 22 days ago

Good night

hashtagWhat is an Integrator?

hashtagGetting Registered

hashtagRegistration Process

hashtagRegistration Transaction

hashtagFund Your Treasury

hashtagManaging Events

hashtagCreate an Event

hashtagEvent Planning Checklist

hashtagQuery Event State

hashtagIssuing Tickets

hashtagBatch Issuance

hashtagTicket ID Management

hashtagFacilitating Transfers

hashtagIntegrator-Initiated Transfer

hashtagWhen to Use Integrator Transfer

hashtagTicket Lifecycle Management

hashtagMark Ticket as Used (Redemption)

hashtagMark Ticket as Void (Cancellation)

hashtagListing Management

hashtagCancel Listings

hashtagWhen to Cancel Listings

hashtagControlling Transfers & Resale

hashtagResale Price Caps

hashtagPrice Cap Enforcement

hashtagUse Cases for Price Caps

hashtagDisabling Transfers

hashtagWhat Happens When Transfers Are Disabled

hashtagUse Cases for Disabling Transfers

hashtagDisabling Resale

hashtagWhat Happens When Resale Is Disabled

hashtagCombining Restrictions

hashtagUpdating Event Settings

hashtagAuthority Management

hashtagUpdate Your Authority Key

hashtagKey Security Best Practices

hashtagMonitoring & Analytics

hashtagQuery Your Integrator State

hashtagMonitor Treasury Balance

hashtagTrack Event Metrics

hashtagIntegration Patterns

hashtagWebhook-Based Integration

hashtagTroubleshooting

hashtagCommon Issues

hashtagDebug Checklist

hashtagNext Steps

What is an Integrator?

Getting Registered

Registration Process

Registration Transaction

Fund Your Treasury

Managing Events

Create an Event

Event Planning Checklist

Query Event State

Issuing Tickets

Batch Issuance

Ticket ID Management

Facilitating Transfers

Integrator-Initiated Transfer

When to Use Integrator Transfer

Ticket Lifecycle Management

Mark Ticket as Used (Redemption)

Mark Ticket as Void (Cancellation)

Listing Management

Cancel Listings

When to Cancel Listings

Controlling Transfers & Resale

Resale Price Caps

Price Cap Enforcement

Use Cases for Price Caps

Disabling Transfers

What Happens When Transfers Are Disabled

Use Cases for Disabling Transfers

Disabling Resale

What Happens When Resale Is Disabled

Combining Restrictions

Updating Event Settings

Authority Management

Update Your Authority Key

Key Security Best Practices

Monitoring & Analytics

Query Your Integrator State

Monitor Treasury Balance

Track Event Metrics

Integration Patterns

Webhook-Based Integration

Troubleshooting

Common Issues

Debug Checklist

Next Steps