Documentation

curl https://txn.dev/api/wallets \
  -H "Authorization: Bearer txn_live_..."

Agent wallet          Job escrow             Worker
────────────          ──────────             ──────
budget + hirer fee →  held                   applies, works
                      held                   submits work
                      ────────────────────→  budget - worker fee
                      ↳ platform fee         ↳ withdraws to bank

import { Txn } from "@txn-dev/sdk"
 
const txn = new Txn(process.env.TXN_API_KEY!)
 
// 1. Find someone who can do the part you cannot
const [photographer] = await txn.workers.find({
  skills: ["photography"],
  max_budget: 200,
  min_rating: 4
})
 
// 2. Escrow the money and put them to work
const { job } = await txn.hire({
  worker_id: photographer.id,
  from: agentWallet.id,
  title: "Photograph three storefronts in Lisbon",
  description: "One wide shot each, daylight, JPEG, by Friday.",
  budget: 150,
  deliver_in_hours: 48
})
 
// 3. Once they have delivered, read it and pay
const { job: delivered } = await txn.jobs.get(job.id)
if (delivered.deliverable) {
  await txn.jobs.release(job.id)
  await txn.jobs.review(job.id, 5, "Exactly the framing I asked for.")
}

const res = await fetch("https://txn.dev/api/cards/authorize", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TXN_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    card_id: card.id,
    amount: 4000,
    currency: "usd",
    merchant_category: "gambling",
    dry_run: true
  })
})
 
const { approved, reason } = await res.json()
// approved: false
// reason: "Merchant category 'gambling' is not permitted on this card"

// 1. The policy, with us
const { card } = await txn.cards.create({
  from: agentWallet.id,
  name: "Lisbon hotel, 3 nights",
  spend_limit: 420,
  allowed_categories: ["lodging"],
  single_use: true
})
 
// 2. The card, with your issuer, on your account
const issued = await stripe.issuing.cards.create({
  cardholder: cardholderId,
  currency: "gbp",
  type: "virtual",
  status: "active",
  // Mirror the ceiling here too. Your issuer's own limits are what hold
  // if we are unreachable, so this is not redundant.
  spending_controls: {
    spending_limits: [{ amount: 42000, interval: "all_time" }],
    allowed_categories: ["lodging"]
  }
})
 
// 3. Join them
await fetch("https://txn.dev/api/cards/link", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TXN_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    card_id: card.id,
    provider: "stripe",
    external_card_id: issued.id
  })
})

// POST /webhooks/issuing
export async function POST(req: Request) {
  const event = stripe.webhooks.constructEvent(
    await req.text(),
    req.headers.get("stripe-signature"),
    process.env.STRIPE_ISSUING_WEBHOOK_SECRET
  )
 
  if (event.type !== "issuing_authorization.request") {
    return Response.json({ received: true })
  }
 
  const auth = event.data.object
 
  // On a request event the top-level amount is always zero. The figure
  // being asked for is in pending_request. Read the wrong one and every
  // authorisation evaluates as free.
  const pending = auth.pending_request
 
  const decision = await fetch("https://txn.dev/api/cards/authorize", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TXN_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      provider: "stripe",
      external_card_id: auth.card.id,
      // Stripe speaks in a currency's minor units; we speak in decimals.
      amount: pending.amount / 100,
      currency: pending.currency,
      merchant_name: auth.merchant_data?.name,
      merchant_category: auth.merchant_data?.category,
      // Idempotency. Replays return the original answer, never a second debit.
      authorization_id: auth.id
    })
  }).then(r => r.json())
 
  // Stripe requires this header and treats its absence as an error rather
  // than a decline, which means your account default decides instead of you.
  return Response.json(
    { approved: decision.approved },
    { headers: { "Stripe-Version": Stripe.API_VERSION } }
  )
}

async function decide(payload) {
  try {
    const res = await fetch("https://txn.dev/api/cards/authorize", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.TXN_API_KEY}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload),
      // Your issuer's window is about two seconds. Leave yourself room to
      // answer: a request still in flight when the window closes is a
      // decision your issuer's default makes for you.
      signal: AbortSignal.timeout(1200)
    })
 
    if (!res.ok) return false
    return (await res.json()).approved
  } catch {
    // Unreachable, slow, or malformed. All the same answer.
    return false
  }
}

{
  "error": "Insufficient balance"
}

npm install @txn-dev/sdk

import { Txn } from "@txn-dev/sdk"
 
const txn = new Txn("txn_live_...")
 
// Create a wallet
const wallet = await txn.wallets.create({
  name: "my-agent",
  currency: "usd",
})
 
// List wallets
const wallets = await txn.wallets.list()
 
// Get a single wallet
const w = await txn.wallets.get("wallet_id")
 
// Transfer funds
const transfer = await txn.pay({
  from: "wallet_a",
  to: "wallet_b",
  amount: 1.50,
  memo: "service fee",
})
 
// Fund via Stripe
const funding = await txn.fund({
  wallet_id: "wallet_a",
  amount: 100,
})

npm install -g @txn-dev/mcp-server

{
  "mcpServers": {
    "txn-payments": {
      "command": "txn-mcp-server",
      "env": {
        "TXN_API_KEY": "txn_live_..."
      }
    }
  }
}

claude mcp add txn -e TXN_API_KEY=txn_test_... -- npx -y @txn-dev/mcp-server

{
  "mcpServers": {
    "txn": {
      "command": "npx",
      "args": ["-y", "@txn-dev/mcp-server"],
      "env": { "TXN_API_KEY": "txn_test_..." }
    }
  }
}

npm install @txn-dev/langchain @langchain/core

import { TxnToolkit } from "@txn-dev/langchain"
 
const toolkit = new TxnToolkit("txn_live_...")
const tools = toolkit.getTools()
 
// Use with a LangGraph agent
import { createReactAgent } from "@langchain/langgraph/prebuilt"
import { ChatAnthropic } from "@langchain/anthropic"
 
const agent = createReactAgent({
  llm: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
  tools,
})