PacketClient

PacketClient is the main entry point for the Packet SDK. Construct one with your wallet and connection, then use it to load or create threads, inboxes, users, keys, and activity accounts.

Constructor

import { PacketClient } from "xpkt-sdk";

const client = new PacketClient(config);

PacketClientConfig

Field	Type	Required	Description
wallet	PacketWallet	No	The signing wallet (defaults to a blank wallet for read-only use)
connection	Connection | string	Yes	Solana RPC connection or endpoint URL
photonRpc	PhotonRpcConfig	No	Optional Light Protocol RPC overrides
defaultTxOptions	PacketTxOptions	No	Default transaction options applied to all write operations
lookUpTableAddress	PublicKey	No	Address lookup table to include in transactions (reduces transaction size)
cluster	"mainnet" | "devnet"	No	Target cluster — defaults to "mainnet"
programId	PublicKey	No	Override the default on-chain program address (for testing or local development)

type PacketClientConfig = {
  wallet?: PacketWallet;
  connection: Connection | string;
  photonRpc?: {
    connection?: Connection | string;
    compressionApiEndpoint?: string;
    proverEndpoint?: string;
  };
  defaultTxOptions?: PacketTxOptions;
  lookUpTableAddress?: PublicKey;
  cluster?: "mainnet" | "devnet";
  programId?: PublicKey;
};

---

Properties

Property	Type	Description
connection	Connection	The Solana connection
walletPublicKey	PublicKey	Public key of the configured wallet
wallet	PacketWallet	The signing wallet
provider	AnchorProvider	Underlying Anchor provider
program	PacketProgram	The Anchor program instance
lightRpc	Rpc	Light Protocol RPC instance
crypto	PacketEncryptionClient	Encryption/decryption helper

---

Updating connection / wallet

client.updateWallet(wallet)

Replaces the signing wallet without rebuilding the client.

client.updateWallet(PacketWallet.fromAdapter(newAdapter));

Returns this

---

client.updateRpc(params)

Updates the Solana connection and/or Photon RPC config.

client.updateRpc({ connection: newConnection });

Returns this

---

Thread methods

client.thread(id)

Returns a thread handle or limited load interface depending on the input:

• PublicKey — returns { load, loadRetrying } (load by address)
• number / BN — returns a full ThreadClient handle (not yet loaded)
• Thread / ThreadClient — wraps the existing data in a new client

// Load by address
const thread = await client.thread(threadAddress).load();

// Get a handle by numeric ID, load separately
const handle = client.thread(42);
await handle.load();

Returns ThreadClient | Pick<ThreadClient, "load" | "loadRetrying">

---

client.createThread(params)

Creates a new thread and sends the first message.

const { receipt, client: thread } = await client.createThread({
  to: recipientPublicKey,
  messageType: MessageType.Text,
  content: "Hello!",
});

See Sending Messages for the full parameter reference.

Returns Promise<TxReceiptWithClient<ThreadClient>>

---

Inbox methods

client.inbox(id)

Loads an inbox by ID or address.

const inbox = await client.inbox(1);           // caller's inbox
const inbox = await client.inbox(inboxAddress);

Returns Promise<InboxClient>

---

client.createInbox(params)

Creates a new inbox.

const { receipt, client: inbox } = await client.createInbox({ inboxId: 1 });

See Inbox and Payment Rules for the full parameter reference.

Returns Promise<TxReceiptWithClient<InboxClient>>

---

Activity methods

client.activity(owner?)

Returns an ActivityClient for the given owner (defaults to the connected wallet). Does not fetch — call .load() to populate.

const activity = client.activity();
await activity.load();

Returns ActivityClient

---

client.createOrLoadActivity(owner?)

Loads the activity client for the given owner. No on-chain transaction required — activity is a virtual index over compressed thread accounts.

const { client: activity } = await client.createOrLoadActivity();

Returns Promise<TxReceiptWithClient<ActivityClient>>

---

User methods

client.user(owner?)

Returns a UserClient handle for the given owner (defaults to connected wallet). Does not fetch.

const handle = client.user();
await handle.load();

Returns UserClient

---

client.loadUser(owner?)

Returns a loaded UserClient.

const user = await client.loadUser();

Returns Promise<UserClient>

---

client.createUser(params)

Creates an on-chain user profile.

const { receipt, client: user } = await client.createUser({
  name: "Alice",
  uri: "https://example.com/alice.json",
});

See User for the full parameter reference.

Returns Promise<TxReceiptWithClient<UserClient>>

---

Key methods

client.key(owner?)

Returns a KeyClient handle. Does not fetch.

Returns KeyClient

---

client.loadKey(owner?)

Returns a loaded KeyClient.

const keyClient = await client.loadKey(recipientPublicKey);
const reader = keyClient.Reader; // use in encrypt()

Returns Promise<KeyClient>

---

client.createKey(params?)

Registers a public encryption key on-chain.

const { client: keyClient } = await client.createKey({
  key: myPublicKeyBytes,
  keyType: PacketKeyType.X25519,
});

If called with no arguments, stores the wallet public key with Ed25519WalletDerivedX25519.

Returns Promise<TxReceiptWithClient<KeyClient>>

---

client.createKeyFromCrypto(owner?)

Registers the key from the active client.crypto identity. Call after useSolanaCryptoKeypair or useWalletPasswordCrypto.

await client.useWalletPasswordCrypto({ password, signMessage });
await client.createKeyFromCrypto();

Returns Promise<TxReceiptWithClient<KeyClient>>

---

Crypto methods

The client.crypto getter returns a PacketEncryptionClient. See Encryption for the full guide.

client.useCrypto(identity)

Sets the active encryption identity manually.

Returns this

---

client.useSolanaCryptoKeypair(keypair)

Sets the identity from a Solana Keypair. Node/server only.

Returns this

---

client.useWalletPasswordCrypto(input)

Derives a deterministic X25519 identity from password + wallet signature. Browser-friendly.

const derived = await client.useWalletPasswordCrypto({
  password: "my-password",
  signMessage: wallet.signMessage,
});

Returns Promise<PacketDerivedCryptoIdentity>

---

client.clearCrypto()

Clears the in-memory crypto identity. Call on logout or wallet switch.

Returns this

---

client.loadReaderForOwner(params)

Loads a PacketReaderInput for a wallet by looking up their registered key on-chain. Optionally falls back to wallet-derived key if no key account is found.

const reader = await client.loadReaderForOwner({
  ownerWallet: recipientPublicKey,
  fallbackToWalletDerived: true,
});

Field	Type	Description
ownerWallet	PublicKey | string	The wallet to look up
fallbackToWalletDerived	boolean	Use wallet-derived key if no key account exists

Returns Promise<PacketReaderInput>

---

client.loadWalletDerivedReader(ownerWallet)

Returns a PacketReaderInput for a wallet using the Ed25519WalletDerivedX25519 algorithm without an on-chain lookup. Use when you know the recipient uses wallet-derived encryption.

const reader = client.loadWalletDerivedReader(recipientPublicKey);

Returns PacketReaderInput

---

Message events

client.messageEvents

Returns a MessageEventsClient for subscribing to real-time message events via WebSocket. The instance is lazily created and cached.

const sub = client.messageEvents.listenIncoming({
  onMessage: async (message, event) => {
    console.log("new message in thread", event.threadId);
  },
});

// later
await sub.stop();

See Message Events for the full reference.

Returns MessageEventsClient

---

TxReceiptWithClient<T>

All create methods return this shape:

interface TxReceiptWithClient<T> {
  receipt: string[];  // transaction signatures
  client: T;         // loaded client instance
}