TipClient Class

The TipClient class is the primary entrypoint for interacting with the TIP protocol and REST API. Construction is synchronous and never touches the network until a method is called.

import { TipClient } from "@tagwise/tip-sdk";

Constructor

new TipClient(options?: TipClientOptions)

Instantiates a new TIP client.

Parameters

Example

const client = new TipClient({
  baseUrl: "https://tip.tagwise.me",
  rpcUrl: "https://api.devnet.solana.com",
});

Read Methods (No Session Required)

resolve(tag: string): Promise<ResolveResponse>

Resolves a tag to its payment wallet and off-chain identity metadata.

• Parameters: tag: string - Raw or canonical handle (e.g. "alice" or "@alice").
• Returns: Promise<ResolveResponse> - The tag identity record.
• Throws: TagInvalidError (malformed format), TagNotFoundError (404 not registered).

const identity = await client.resolve("@alice");
console.log(identity.wallet); // "4vcgrBuzoWw3kBanVTtx7Pi1v9WyTJBJQsFAQMqjJZjx"

identity(tag: string): Promise<IdentityResponse>

Fetches the complete identity record for a tag including off-chain profile fields.

• Parameters: tag: string
• Returns: Promise<IdentityResponse>
• Throws: TagNotFoundError

const profile = await client.identity("alice");
console.log(profile.displayName, profile.avatar);

availability(tag: string): Promise<AvailabilityResponse>

Checks if a handle is available for registration.

• Parameters: tag: string
• Returns: Promise<AvailabilityResponse> - { tag: string, available: boolean, reason?: AvailabilityReason }

const res = await client.availability("my_tag");
if (res.available) {
  console.log("Ready to register!");
}

search(q: string): Promise<SearchResultItem[]>

Searches registered tags by handle or display name prefix.

• Parameters: q: string - Search query string.
• Returns: Promise<SearchResultItem[]> - Array of matching search items.

const results = await client.search("ali");
// [{ tag: "@alice", displayName: "Alice", avatar: "..." }]

qr(tag: string): Promise<QrResponse>

Generates a Solana Pay URL and checkout payment link payload for a tag.

• Parameters: tag: string
• Returns: Promise<QrResponse> - { tag, solanaPayUrl, paymentLink }

const qrData = await client.qr("alice");
console.log(qrData.solanaPayUrl); // "solana:4vcgrBuzoWw3k..."

paymentLink(tag: string): Promise<PaymentLinkResponse>

Retrieves the web checkout URL for a tag.

• Parameters: tag: string
• Returns: Promise<PaymentLinkResponse> - { tag, url }

const link = await client.paymentLink("alice");
console.log(link.url); // "https://tagwise.me/pay/@alice"

Authentication Methods

connect(signer: Signer): Promise<string>

Executes the full Sign-In With Solana (SIWS) authentication flow: requests a challenge, prompts the signer to sign it, verifies the signature, and stores the JWT session token in memory.

• Parameters: signer: Signer - Object exposing publicKey: string and signMessage(bytes: Uint8Array): Promise<Uint8Array>.
• Returns: Promise<string> - The authenticated public key.

const pubkey = await client.connect({
  publicKey: wallet.publicKey.toBase58(),
  signMessage: (bytes) => wallet.signMessage(bytes),
});

challenge(pubkey: string): Promise<string>

Requests a single-use text challenge string for pubkey.

• Parameters: pubkey: string - Base58 Solana public key.
• Returns: Promise<string> - Challenge message string.

verify(pubkey: string, message: string, signature: string): Promise<string>

Verifies a signed challenge message and sets the session token.

• Parameters: pubkey: string, message: string, signature: string (Base58 signature).
• Returns: Promise<string> - JWT session token.

setSession(token: string, pubkey: string): void

Restores a previously acquired JWT session token into memory.

client.setSession(tokenFromStorage, pubkeyFromStorage);

disconnect(): void

Clears the active session token from client memory.

client.disconnect();

Getters

• get token(): string | undefined: Returns the active JWT session token or undefined.
• get connectedPubkey(): string | undefined: Returns the connected public key or undefined.

Write Methods (Session Required)

register(params: RegisterParams): Promise<UnsignedTransactionResponse>

Builds an unsigned register_tag Solana transaction.

• Parameters: params: RegisterParams - { tag: string, wallet?: string, feePayer?: string }.
• Returns: Promise<UnsignedTransactionResponse> - { transaction: string, pda: string, lastValidBlockHeight: number }.
• Throws: NoSessionError, TagInvalidError, RateLimitedError.

const res = await client.register({ tag: "myhandle" });

Pass feePayer to have a sponsor cover the account rent and network fee instead of the owner. The owner recorded on the tag is always the connected pubkey; feePayer only decides who pays. When feePayer differs from the owner, the returned transaction requires signatures from both before it can be submitted:

const res = await client.register({ tag: "myhandle", feePayer: sponsorWallet.publicKey.toBase58() });

updateWallet(tag: string, newWallet: string): Promise<UnsignedTransactionResponse>

Builds an unsigned update_wallet transaction to change the tag's on-chain destination address.

• Parameters: tag: string, newWallet: string
• Returns: Promise<UnsignedTransactionResponse>
• Throws: ForbiddenError (if session pubkey is not tag owner).

const res = await client.updateWallet("alice", "9zQP...");

updateProfile(tag: string, fields: UpdateProfileFields): Promise<IdentityResponse>

Patches off-chain metadata fields in the database mirror.

• Parameters: tag: string, fields: UpdateProfileFields - { displayName?, avatar?, bio?, preferredToken? }.
• Returns: Promise<IdentityResponse>

await client.updateProfile("alice", { displayName: "Alice" });

signAndSendTransaction(unsignedTx: string, signer: TransactionSigner): Promise<string>

Signs an unsigned base64 transaction and broadcasts it to Solana RPC.

• Parameters: unsignedTx: string (Base64), signer: TransactionSigner.
• Returns: Promise<string> - Solana transaction signature.

const txId = await client.signAndSendTransaction(res.transaction, walletAdapter);