Documentation

Quickstart~2 min

Get a wallet created and a transfer sent in four steps. You will need a txn.dev account and an API key from the dashboard.

npm install @txn-dev/sdk

import { Txn } from "@txn-dev/sdk"
 
const txn = new Txn("txn_live_...")

const wallet = await txn.wallets.create({
  name: "my-agent",
  currency: "usd"
})

await txn.pay({
  from: wallet.id,
  to: "wallet_receiver_id",
  amount: 0.50,
  memo: "task completed"
})

Authentication

All API requests require a Bearer token in the Authorization header. Create API keys from the dashboard.

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

• Keys are shown once at creation. Store them securely.
• All keys are scoped to your organization.
• Revoke compromised keys immediately from the dashboard.

Core Concepts

txn.dev is a ledger for autonomous agents. Understanding a few primitives will help you build on it effectively.

Wallets

{
  "name": "translation-agent",
  "currency": "usd",
  "metadata": { "agent_version": "2.1" }
}

{
  "wallet": {
    "id": "w-a1b2c3d4",
    "name": "translation-agent",
    "balance": "0",
    "currency": "usd",
    "created_at": "2026-03-28T12:00:00Z"
  }
}

{
  "wallets": [
    {
      "id": "w-a1b2c3d4",
      "name": "translation-agent",
      "balance": "150.00",
      "currency": "usd"
    }
  ]
}

Transfers

{
  "from": "wallet_sender_id",
  "to": "wallet_receiver_id",
  "amount": 0.003,
  "memo": "translated 340 words en>fr",
  "idempotency_key": "job_7f3a9c"
}

{
  "transaction": {
    "id": "txn_x1y2z3",
    "from_wallet_id": "wallet_sender_id",
    "to_wallet_id": "wallet_receiver_id",
    "amount": "0.003",
    "type": "transfer",
    "status": "completed",
    "created_at": "2026-03-28T12:01:00Z"
  },
  "fee": {
    "amount": "0.00007500",
    "net": "0.00292500",
    "rate": "2.5%"
  }
}

Funding

{
  "wallet_id": "w-a1b2c3d4",
  "amount": 50.00
}

{
  "checkout_url": "https://checkout.stripe.com/...",
  "session_id": "cs_live_..."
}

Error Handling

All errors return a JSON object with an error field.

{
  "error": "Insufficient balance"
}

TypeScript SDK

The @txn-dev/sdk package is a zero-dependency client for the txn.dev API. It works in Node.js, Deno, Bun, and any runtime with fetch.

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,
})

MCP Server

The @txn-dev/mcp-server package lets AI assistants like Claude manage wallets and payments via the Model Context Protocol. Install it globally, then add it to your MCP client config.

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

Claude Desktop

Add this to your claude_desktop_config.json:

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

Available tools

LangChain

The @txn-dev/langchain package provides a TxnToolkit that plugs directly into LangChain and LangGraph agents.

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,
})

The toolkit exposes the same five tools as the MCP server: create_wallet, list_wallets, get_balance, pay, and fund_wallet.