TypeScript SDK

Create a client

SDK 0.3 signs with a delegated P256 access key. The rootAddress is the owner whose funds are used. Mainnet is the default; choose testnet explicitly for Moderato.

import { TempoKey } from "@tempokey/sdk";

const agent = new TempoKey({
  network: "mainnet",
  privateKey: process.env.AGENT_PRIVATE_KEY,
  rootAddress: process.env.OWNER_ADDRESS,
  // rpcUrl: "https://your-tempo-mainnet-provider.example",
});

Payments and batches

const payment = await agent.pay({
  to: recipient, amount: 0.01, token: "PathUSD",
});
console.log(payment.hash);

const batch = await agent.batchPay([
  { to: firstRecipient, amount: 0.01 },
  { to: secondRecipient, amount: 0.02 },
], { token: "USDC.e" });
console.log(batch.summary, batch.results);

Amounts use human token units. Both mainnet tokens have six decimal places. pay returns hash, from, to, amount, amountRaw and token. Raw amounts are bigint values; convert them to strings before JSON serialization.

Quotes and token swaps

const quote = await agent.getQuote({
  from: "PathUSD", to: "USDC.e", amount: 1,
});

const swap = await agent.swap({
  from: "PathUSD", to: "USDC.e", amount: 1, slippage: 1,
});
console.log(swap.hash);

slippage is a percentage; the default is 2. swap approves the input token and then submits the DEX transaction. The agent must have the necessary call permissions and available token budget. A successful approval does not guarantee that the subsequent swap succeeds.

In SDK 0.3, amountOut and rate in the swap result are based on the quote. Use the transaction receipt or token balances to reconcile actual settlement. Quotes can change before execution and available liquidity is not guaranteed.

Balances and permissions

const balance = await agent.getBalance("PathUSD");
const balances = await agent.getAllBalances();
const limit = await agent.getRemainingLimit("USDC.e");
console.log(balance.formatted, limit.formatted, limit.periodEnd);

console.log(agent.address);     // Access-key address
console.log(agent.rootAddress); // Owner wallet
console.log(agent.tokens);      // Tokens for this network

getBalance reads the owner's token balance. getRemainingLimit reads the agent's remaining budget for the requested token; periodEnd is a Unix timestamp or null for a lifetime limit. getAllBalances currently reports zero for an individual token read that fails; use getBalance when your application must distinguish a read error from a zero balance.

Handle failures explicitly

import { SpendingLimitError, RecipientNotAllowedError } from "@tempokey/sdk";

try {
  await agent.pay({ to: recipient, amount: 0.01 });
} catch (error) {
  if (error instanceof SpendingLimitError) {
    console.error("Agent budget exhausted");
  } else if (error instanceof RecipientNotAllowedError) {
    console.error("Recipient is outside the allowlist");
  } else {
    throw error;
  }
}

The SDK also exports ValidationError, TokenNotFoundError, InsufficientBalanceError, InsufficientLiquidityError, NetworkError and TransactionError. SDK payment methods do not provide the hosted API's idempotency store.