Integrate a TSN Payment Flow

Use the TSN SDK to check readiness, resolve a recipient TIN, request wallet authorization, and follow payment status.

This guide describes the application boundary. Your app configures service URLs, displays the recipient and payment details, and asks the connected wallet to approve the exact authorization. TSN services verify the submitted work; a confirmed Solana transaction is the evidence that settlement executed.

The TSN SDK is currently a private workspace package. It is not published to the public npm registry. See the SDK overview for package access and the SDK reference for exported functions.

The snippets illustrate integration stages and assume caller-supplied variables. Complete typed examples and the full generated reference provide verified inputs and signatures.

Check readiness

Pass the service endpoints selected by your application. A readiness response is not a payment authorization or settlement confirmation.

import { getTsnNetworkStatus } from "@trustlink/tsn-sdk";

const network = await getTsnNetworkStatus({
  live: {
    node: process.env.TSN_NODE_URL,
    receiver: process.env.TSN_RECEIVER_URL,
    rpc: process.env.TSN_RPC_URL,
  },
});

if (!network.readyForNativeTransactions) {
  throw new Error("TSN services are not ready");
}

Resolve the recipient

TIN resolution returns the owner-provided display identity for the sender to review. In a trusted backend, the SDK can resolve the TIP registry using the protected lookup secret. Never include that secret in browser code or a wallet authorization.

import { Connection } from "@solana/web3.js";
import { resolveTinV1Identity } from "@trustlink/tsn-sdk/tins";

const recipient = await resolveTinV1Identity({
  connection: new Connection(process.env.TSN_RPC_URL!, "confirmed"),
  tin: recipientTin,
  lookupSecret: process.env.TINS_LOOKUP_SECRET!,
  programId,
});

if (!recipient) throw new Error("TIN could not be resolved");

The display name helps the sender confirm the intended recipient; it is not legal identity verification. The wallet should show the amount, asset, recipient TIN, and applicable fee before asking the sender to sign.

Request wallet authorization

Use the SDK to build the canonical payment authorization from the reviewed recipient and asset details. Ask the connected wallet to sign that exact message; do not substitute an operator key for the sender’s approval.

import { Connection, PublicKey } from "@solana/web3.js";
import { createTcapAssetPaymentAuthorization } from "@trustlink/tsn-sdk";

const authorization = await createTcapAssetPaymentAuthorization({
  connection: new Connection(process.env.TSN_RPC_URL!, "confirmed"),
  depositor: new PublicKey(senderWallet),
  mint: new PublicKey(tokenMint),
  senderWallet,
  senderIdentity: senderWallet,
  receiverIdentity: `tin:${recipientTin}`,
  recipientDisplayName: recipient.displayName,
  recipientDisplayNameSource: recipient.displayName.trim() ? "owner-provided" : "not provided",
  amount,
  senderFeeAmount,
  totalTokenRequiredUi: amount + senderFeeAmount,
  fundingMode: "tcap_deposit_v2",
});

const signature = await wallet.signMessage(
  new TextEncoder().encode(authorization.message),
);

If the payment requires a separately signed token-deposit transaction, show that transaction in the wallet for approval as well. A message signature and a token transfer are distinct authorizations.

Submit and follow status

Submit the SDK-built intent with the sender’s signature and any required signed funding transaction. The response identifies accepted work; it does not mean the Node has verified it or that funds have settled. Follow the payment lifecycle and verify the confirmed transaction signature on the selected Solana cluster.

import {
  TsnHttpClient,
  buildPaymentAuthorizationIntentRequest,
} from "@trustlink/tsn-sdk";

const request = buildPaymentAuthorizationIntentRequest({
  paymentId,
  recipientHash: recipient.ownerPubkeyHash,
  recipientTin,
  tokenMintAddress: authorization.asset.mint,
  tokenDecimals: authorization.asset.decimals,
  senderWallet,
  senderAuthorizationMessage: authorization.message,
  senderAuthorizationSignature: Buffer.from(signature).toString("base64"),
  senderAuthorizationNonce: authorization.nonce,
  senderAuthorizationIssuedAt: authorization.issuedAt,
  senderAuthorizationExpiresAt: authorization.expiresAt,
  senderFeeAmount,
  senderSignedFundingTransaction,
  senderFundingMode: "tcap_deposit_v2",
  amount,
  source: "my-tsn-app",
});

const client = new TsnHttpClient({ baseUrl: process.env.TSN_NODE_URL! });
const intent = await client.postIntent(request);
console.log(intent.id, intent.status);

For Node, Receiver, Cranker, program-build, and deployment procedures, use the repository’s root documentation. This site stays focused on protocol concepts and application SDK use.