Skip to main content

Payments & Escrow

Packet lets inbox owners require a SOL payment before a sender can open a new thread. Optionally, that payment can be held in escrow until the receiver manually releases it.

Payment Rules​

A payment rule is attached to an inbox. Any createThread call targeting that inbox must include a payment satisfying the rule, or the transaction will fail.

Configuring a Payment Rule​

Payment rules are set when creating an inbox or by editing an existing one:

// Create inbox with a 0.05 SOL payment wall
await client.createInbox({
  inboxId: 0,
  payment: {
    amount: 0.05 * LAMPORTS_PER_SOL,
    mint: WSOL_MINT,
    escrow: false, // pay immediately to receiver
  },
});
FieldTypeDescription
amountBN | numberRequired payment amount in token base units
mintPublicKeyToken mint (currently WSOL)
escrowbooleanIf true, payment is held in escrow until released
destinationPublicKeyOptional: override the destination token account

Auto-Payment by SDK​

When a sender calls createThread against an inbox with a payment rule, the SDK automatically attaches the required payment. The sender does not need to pass payment explicitly if they want to satisfy the default rule.

Escrow​

When escrow: true is set on the inbox payment rule, payments from new threads are held in a per-thread escrow account rather than transferred immediately to the receiver.

Escrow Lifecycle​

1. Sender opens thread  →  Payment held in thread escrow account
2. Receiver inspects message
3. Receiver calls approveEscrow()  →  Payment released to receiver
   (or sender can withdraw if rules allow)

Releasing Escrow​

// Receiver approves the escrow
await thread.approveEscrow();

// Receiver withdraws the released funds
await thread.withdrawEscrow();

Checking Escrow Status​

const thread = await client.thread(42).load();
const escrow = thread.Thread.escrowPayment;

if (escrow) {
  console.log("amount:", escrow.amount.toString());
  console.log("approved:", escrow.approved);
}

CLI​

# Create inbox with 0.05 SOL payment + escrow
packet message create-inbox --inbox 0 --payment-sol 0.05 --escrow

# Approve escrow on thread 42
packet message escrow approve --thread 42

# Withdraw released escrow
packet message escrow withdraw --thread 42

SDK Reference​