Toll Docs

npm install @rajkaria123/toll-sdk

// 1. Install
// npm install @rajkaria123/toll-sdk

// 2. Create a wallet (saved to ~/.toll/wallet.json)
import { WalletManager, TollClient } from "@rajkaria123/toll-sdk"

const wm = new WalletManager()
const wallet = wm.getOrCreate("mainnet")
console.log("Your address:", wallet.publicKey)
// → Fund this address with USDC on Stellar mainnet
//   (send to USDC asset: CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI)
//   Minimum: 0.05 USDC for 5 test calls at api.tollpay.xyz

// 3. Call a paid tool — auto-signs the 402 and pays
const toll = new TollClient({
  serverUrl: "https://api.tollpay.xyz",
  secretKey: wallet.secretKey,
  budget: { maxPerCall: "0.05", maxDaily: "1.00" },
})

const result = await toll.callTool("search_competitors", { query: "project management" })
if (result.success) {
  console.log(result.data)          // tool output
  console.log(result.paid)          // true — 0.01 USDC paid on Stellar mainnet
}

console.log(toll.getSpending())
// { totalSpent: 0.01, callCount: 1, dailyRemaining: 0.99 }

npm install @rajkaria123/toll-gateway @rajkaria123/toll-stellar

{
  "network": "mainnet",
  "payTo": "G...YOUR_STELLAR_ADDRESS",
  "facilitatorUrl": "https://channels.openzeppelin.com/x402",
  "tools": {
    "my_free_tool":   { "price": "0",    "currency": "USDC" },
    "my_paid_tool":   { "price": "0.05", "currency": "USDC" }
  }
}

import express from "express"
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
import { tollMiddleware, loadConfig, createHealthRoutes } from "@rajkaria123/toll-gateway"

const config = loadConfig("./toll.config.json")
const app = express()

app.use(express.json())
app.use("/mcp", tollMiddleware(config))    // paywall + spending policy
app.use(createHealthRoutes(config))        // /health, /health/tools, /cost

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined })
  await mcpServer.connect(transport)
  await transport.handleRequest(req, res, req.body)
})

app.listen(3002)

// Claude Desktop / any MCP client config
{
  "mcpServers": {
    "toll-tools": {
      "url": "https://proxy.tollpay.xyz/mcp?target=https://api.tollpay.xyz/mcp",
      "transport": "streamable-http"
    }
  }
}

"search_competitors": {
  "price": "0.01",
  "currency": "USDC",
  "rateLimit": {
    "free": 5,
    "perHour": true
  }
}

"spendingPolicy": {
  "maxPerCall": "0.10",         // No single call costs more than $0.10
  "maxDailyPerCaller": "1.00",  // Each caller capped at $1/day
  "maxDailyGlobal": "10.00"    // Total daily cap across all callers
}

"0.01"  USDC  →  100000   base units (stroops)
"0.001" USDC  →  10000    base units
"1.00"  USDC  →  10000000 base units

# Start the Toll Proxy locally — auto-creates a Stellar wallet
npx @rajkaria123/toll-proxy --target https://api.tollpay.xyz/mcp

# Or with custom budget limits
npx @rajkaria123/toll-proxy \
  --target https://api.tollpay.xyz/mcp \
  --budget-daily 5.00 \
  --budget-per-call 0.50

# Or use the hosted proxy (no install needed):
# https://proxy.tollpay.xyz/mcp?target=https://api.tollpay.xyz/mcp

// Add to Claude Desktop / Cursor MCP config:
{
  "mcpServers": {
    "my-paid-tools": {
      "url": "https://proxy.tollpay.xyz/mcp?target=https://api.tollpay.xyz/mcp",
      "transport": "streamable-http"
    }
  }
}
// Or use localhost if running the proxy locally:
// "url": "http://localhost:3010/mcp?target=https://api.tollpay.xyz/mcp"

--budget-daily 5.00    # Max $5 USDC per day (default)
--budget-per-call 0.50  # Max $0.50 per individual call

https://proxy.tollpay.xyz/mcp?target=https://api.tollpay.xyz/mcp

npx @rajkaria123/toll-cli register --url https://your-server.com/mcp

// Discover tools programmatically
const resp = await fetch(
  "https://tollpay.xyz/api/registry/discover?q=search&maxPrice=0.05"
)
const { tools } = await resp.json()
// 18 tools across 5 servers — free and paid
// [{ name: "search_competitors", price: "0.01", server: { url: "..." }, ... }]

import { WalletManager } from "@rajkaria123/toll-sdk"

const wallet = new WalletManager()

// Auto-creates ~/.toll/wallet.json with a Stellar Ed25519 keypair
const { publicKey, secretKey } = wallet.getOrCreate("mainnet")

// Get funding instructions
console.log(wallet.fundingInstructions(publicKey))

npm install @rajkaria123/toll-sdk

import { TollClient } from "@rajkaria123/toll-sdk"

const toll = new TollClient({
  serverUrl: "https://your-server.com",
  secretKey: "S...",  // Stellar Ed25519 secret key
  budget: {
    maxPerCall: "0.10",
    maxDaily: "5.00",
  },
})

// Free tool — no payment
const health = await toll.callTool("health_check")

// Paid tool — auto-handles 402 → sign → retry
const result = await toll.callTool("search_competitors", {
  query: "AI agent frameworks"
})

const manifest = await toll.discoverTools()
// Returns: { tools: [{ name, price, currency, paymentMode }], network }

const report = toll.getSpending()
// { totalSpent, callCount, byTool, dailyRemaining }

toll.on("payment", (ev, data) => console.log(`Paid ${data.amount} for ${data.tool}`))
toll.on("budget_warning", (ev, data) => console.log(`${data.remaining} remaining`))
toll.on("error", (ev, data) => console.error(data.error))

CREATE TABLE transactions (
  id          TEXT PRIMARY KEY,     -- UUID
  tool        TEXT NOT NULL,        -- tool name
  caller      TEXT,                 -- Stellar address or IP
  amount_usdc REAL NOT NULL,        -- payment amount
  protocol    TEXT NOT NULL,        -- "x402" or "mpp"
  tx_hash     TEXT,                 -- on-chain transaction hash
  created_at  INTEGER NOT NULL      -- Unix timestamp (ms)
);

# Check server account transactions
curl https://horizon.stellar.org/accounts/GDQRUDNV3D3DF3KMVPWHFW7Y676AEPL7U6CEXKCD2F7HLEPFF5HKOEUV/operations?order=desc&limit=20

# Or try a paid tool yourself (returns HTTP 402)
curl -X POST https://api.tollpay.xyz/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_competitors","arguments":{"query":"test"}}}'