Payments

type Payment = {
  id: string;
  /** "pending" until the on-chain tx confirms; updated via get() or webhook. */
  status: "pending" | "confirmed" | "failed";
  /** Transaction hash. Set as soon as Privy accepts the signed RPC. */
  tx_hash: string | null;
  amount_usdc: string;
  to: string;
  from: string;
  memo: string | null;
  idempotency_key: string | null;
  created_at: string;
};

type PaymentCreateInput = {
  /** Agent's user-provided id, e.g. "research-bot". */
  agent_id: string;
  /** Sender wallet address. Must be in this API key's (account, mode)
   *  and must have an active grant for the agent. */
  wallet: string;
  /** Recipient EVM address. */
  to: string;
  /** Decimal USDC amount as a string, e.g. "10" or "2.50". */
  amount_usdc: string;
  /** Optional memo, max 200 chars. Stored alongside the transaction. */
  memo?: string;
  /** Optional idempotency key, max 64 chars. Scoped to (account, mode). */
  idempotency_key?: string;
};

const payment = await tally.payments.create({
  agent_id: "research-bot",
  wallet: "0x7a3f...",
  to: "0xC0fee...",
  amount_usdc: "4.50",
  memo: "arxiv API access",
  idempotency_key: "invoice-2026-04-117",
});

console.log(payment.status, payment.tx_hash);
// → "pending" 0xabc...

const p = await tally.payments.get("pmt_01HXYZ...");

async function chargeWithRetry() {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await tally.payments.create({
        agent_id,
        wallet,
        to,
        amount_usdc,
        idempotency_key: `invoice-${invoiceId}`, // deterministic
      });
    } catch (err) {
      if (err instanceof RateLimitError) await sleep(1000 * 2 ** attempt);
      else throw err;
    }
  }
}

let p = await tally.payments.create({ ... });

while (p.status === "pending") {
  await new Promise((r) => setTimeout(r, 2_000));
  p = await tally.payments.get(p.id);
}

if (p.status === "failed") {
  // Handle the on-chain failure.
}