Getting Started

txfence requires Node.js 18+ and a package manager (npm, pnpm, or yarn).

Installation

Install @txfence/core plus the chain adapter you need.

pnpm


pnpm add @txfence/core @txfence/evm

npm


npm install @txfence/core @txfence/evm

yarn


yarn add @txfence/core @txfence/evm

Your first policy-gated agent

Define a policy

A Policy is a flat typed object — no rules array, no match clauses, no default-effect.

policy.ts


import type { Policy } from "@txfence/core";
 
export const policy: Policy = {
  chains:                 ["ethereum"],
  maxSpendPerTx:          { token: "USDC", amount: 1_000n, decimals: 6 },
  allowedContracts:       [{ address: "0xYOUR_CONTRACT", chain: "ethereum" }],
  requireSimulation:      true,
  gasBufferMultiplier:    1.2,
  humanApprovalThreshold: { token: "USDC", amount: 10_000n, decimals: 6 },
  humanApprovalTimeoutMs: 30_000,
  capLockMode:            "per-agent",
};

Six policy checks run synchronously on every action: chain allowlist, contract allowlist, spend cap, slippage declared (swaps), simulation-required, and gas buffer. The first failing check short-circuits with a PolicyRejectionReason.

Create the agent

createAgent wires the policy, adapters, RPC endpoints, and an executor into a single instance.

agent.ts


import { createAgent } from "@txfence/core";
import {
  simulateEvmAction,
  executeEvmAction,
  privateKeySigner,
} from "@txfence/evm";
import { policy } from "./policy";
 
const signer = privateKeySigner(process.env.PRIVATE_KEY as `0x${string}`);
 
export const agent = createAgent(
  { chains: ["ethereum"], policies: policy, signer },
  { ethereum: { simulate: simulateEvmAction } },
  { ethereum: "https://ethereum.publicnode.com" },
  (action, chainId, rpcUrl, evaluation, simulation) =>
    executeEvmAction(action, chainId, rpcUrl, signer, evaluation, simulation),
);

Submit an action

Every proposed action goes through agent.submit({ action, policy }). The pipeline runs policy evaluation → temporal rules → simulation → staleness check → cap lock → approval → execution.

run.ts


import { agent } from "./agent";
import { policy } from "./policy";
import type { Action } from "@txfence/core";
 
const action: Action = {
  kind:  "transfer",
  chain: "ethereum",
  token: { token: "ETH", amount: 100_000_000_000_000_000n, decimals: 18 },
  to:    "0xRECIPIENT",
};
 
const result = await agent.submit({ action, policy });
 
switch (result.status) {
  case "success":
    console.log("tx hash:", result.receipt.txHash);
    break;
  case "policy_rejected":
    console.log("rejected:", result.evaluation.rejectionReason);
    break;
  case "simulation_failed":
    console.log("simulation failed:", result.simulation.revertReason);
    break;
  case "simulation_stale":
    console.log("simulation stale by", result.stalenessMs, "ms — retry");
    break;
  case "approval_timeout":
    console.log("human approval timed out — cancel-on-timeout is the default");
    break;
  case "execution_failed":
    console.log("execution failed:", result.reason.code);
    break;
}

ExecutionResult is a discriminated union — TypeScript forces you to handle every outcome.

Test without broadcasting

Use agent.dryRun() to walk the pipeline without sending the transaction. Cap locks are acquired then immediately released, so the dry run never consumes budget.


# CLI equivalent — exits 1 if anything would block
npx txfence dry-run --kind transfer --chain ethereum --to 0xRECIPIENT \
  --token ETH --amount 100000000000000000

What happens inside `submit()`

The pipeline runs through ordered stages, short-circuiting on the first blocker:

Policy evaluation — six static checks against action + policy
Temporal rules — sliding-window predicates over recent pipeline events (only if policy.temporalRules and an EventStore are configured)
Simulation — adapter.simulate() returns gas estimate, revert prediction, and caveats
Staleness check — if policy.simulationStalenessMs is set, reject if simulation is too old
Cap lock acquire — two-phase reservation against the per-agent or shared cap
Human approval — webhook dispatch + poll, when action value ≥ humanApprovalThreshold
Execution — executor signs and broadcasts
Cap lock commit / release — depending on outcome

Next Steps

Core Concepts — Policy object, Action types, pipeline stages
Guides — 20 walkthroughs covering every feature (composite policies, intent execution, MEV protection, formal verification, …)
API Reference — typed signatures for every package
Architecture — how the pipeline is structured internally