feat: add stellar_transaction_history tool for account transaction & operation lookup

[Sayandeep-the-coder]

Title

feat: add stellar_transaction_history tool for account transaction & operation lookup

---

Body

🧩 Problem

AgentKit currently has no way for an AI agent to query the transaction or operation history of a Stellar account.

This is a critical gap because agents need to inspect what has happened on an account before executing any DeFi operation (swap, bridge, LP deposit, payment). Without this, agents operate blindly.

Current pain points:

• ❌ No way to check if a wallet has recent activity before swapping
• ❌ No way to verify a payment was received
• ❌ No way to audit what operations (mint, fund, create_campaign) were called on contracts
• ❌ Failures surface as raw Horizon API errors rather than context-aware messages

---

✅ Proposed Solution

Add a new DynamicStructuredTool — stellar_transaction_history — and a agent.transactions.* namespace to AgentClient.

Tool: stellar_transaction_history

Two actions in a single tool:

Action	Description
get_transactions	Recent transactions: hash, status, fee, memo, ledger, operation count
get_operations	Recent operations: payments, swaps, contract invocations, trustlines, etc.

Supported Operation Types

Type	Description
payment	XLM or token transfers between accounts
invoke_host_function	Soroban smart contract calls (mint, fund, create_campaign, etc.)
change_trust	Adding or removing asset trustlines
create_account	Funding a new Stellar account
path_payment_strict_send	DEX best-route swap (strict send)
path_payment_strict_receive	DEX best-route swap (strict receive)
manage_sell_offer / manage_buy_offer	SDEX order book operations

---

🚀 AgentClient Integration

import { AgentClient } from "stellartools";

const agent = new AgentClient({ network: "testnet" });

// Get 10 most recent transactions
const txs = await agent.transactions.getTransactions({ limit: 10 });

// Get operations for any account
const ops = await agent.transactions.getOperations({
  publicKey: "<your_wallet_address>",
  network: "testnet",
  limit: 10,
  order: "desc",
});

---

🤖 LangChain Agent Usage

import { StellarTransactionHistoryTool } from "stellartools";

// get_transactions — high-level tx records
const txResult = await StellarTransactionHistoryTool.invoke({
  action: "get_transactions",
  publicKey: "<your_wallet_address>",
  network: "testnet",
  limit: 5,
  order: "desc",
});

// get_operations — granular per-operation detail
const opResult = await StellarTransactionHistoryTool.invoke({
  action: "get_operations",
  publicKey: "<your_wallet_address>",
  network: "testnet",
  limit: 10,
  includeFailedTxs: false,
});

---

🌐 Live Demo — Real Testnet Output

Tested against wallet <your_wallet_address> on Stellar testnet:

get_transactions output

═══ Transaction History (10 records) ═══

[1] Hash     : ebdfe0b2650a84cc0f7fd46904fcaeb7639e5d71f9168106d664ae037faf7abd
    Date     : 2026-04-29T16:05:37Z
    Status   : ✅ Success
    Ops      : 1
    Ledger   : 2294397
    Fee      : 100 stroops

[2] Hash     : 8799137d2d41e71826e4fa2d7c03288338ea96f0937ce29db9124e597618bd2c
    Date     : 2026-04-29T16:05:17Z
    Status   : ✅ Success
    Ops      : 1
    Ledger   : 2294393
    Fee      : 100 stroops

[3] Hash     : 5d4c4e92d219c21609a3faa1091f6a3f5ebf07e62df70e675dae02aa02a5db7c
    Date     : 2026-04-29T16:03:52Z
    Status   : ✅ Success
    Ops      : 1
    Ledger   : 2294376
    Fee      : 100 stroops

[4] Hash     : d2b747d7da1bf079638b5611a96aaa96824416a36bf4c93800e82df938c2c277
    Date     : 2026-04-29T08:50:00Z
    Status   : ✅ Success
    Ops      : 1
    Ledger   : 2289178
    Fee      : 99351 stroops

[5] Hash     : f7cba1a45fd596875850ffaf83597b295455c9bd9c2ab2fe2f4590c24aaa9db8
    Date     : 2026-04-24T17:54:30Z
    Status   : ✅ Success
    Ops      : 1
    Ledger   : 2209454
    Fee      : 18291780 stroops

[6] Hash     : ca30a5cfa21b4006f2d77713ee87f3cf07ef9a2b6bd9a1244178d4b078141259
    Date     : 2026-04-03T18:37:09Z
    Status   : ✅ Success
    Ops      : 1
    Ledger   : 1847711
    Fee      : 100 stroops

---

get_operations output — All 3 operation types found on this account

═══ Operation History (10 records) ═══

─── Type: payment ──────────────────────────────────────────────
[1] Type             : payment
    Date             : 2026-04-29T16:05:37Z
    Source Account   : GAODT4TCZBVPDRVNOVNGDGGSF4LTTO7EIXW56632KL6ZNV5LPVN3ITKU
    Transaction Hash : ebdfe0b2650a84cc...
    asset_type       : "native"
    from             : "GAODT4...ITKU"
    to               : "GA3UD3...OW4B"
    amount           : "0.0300000"

[2] Type             : payment
    Date             : 2026-04-29T16:05:17Z
    Transaction Hash : 8799137d2d41e718...
    asset_type       : "native"
    from             : "GAODT4...ITKU"
    to               : "GA3UD3...OW4B"
    amount           : "0.0300000"

[3] Type             : payment
    Date             : 2026-04-29T16:03:52Z
    Transaction Hash : 5d4c4e92d219c216...
    asset_type       : "native"
    from             : "GAODT4...ITKU"
    to               : "GA3UD3...OW4B"
    amount           : "1.0000000"

─── Type: invoke_host_function (Soroban) ───────────────────────
[4] Type             : invoke_host_function
    Date             : 2026-04-29T08:50:00Z
    Transaction Hash : d2b747d7da1bf079...
    function         : "HostFunctionTypeHostFunctionTypeInvokeContract"
    called           : fund()
    contract         : campaign contract

[5] Type             : invoke_host_function
    Date             : 2026-04-28T19:01:38Z
    Transaction Hash : ea209601847788f8...
    function         : "HostFunctionTypeHostFunctionTypeInvokeContract"
    called           : fund()
    contract         : campaign contract

[6] Type             : invoke_host_function
    Date             : 2026-04-24T17:54:30Z
    Transaction Hash : f7cba1a45fd59687...
    function         : "HostFunctionTypeHostFunctionTypeInvokeContract"
    called           : create_campaign("a weather app")

[7] Type             : invoke_host_function
    Date             : 2026-04-03T19:10:46Z
    Transaction Hash : 82904931b4de1b4d...
    function         : "HostFunctionTypeHostFunctionTypeInvokeContract"
    called           : mint()

─── Type: change_trust ─────────────────────────────────────────
[8] Type             : change_trust
    Date             : 2026-04-03T18:37:09Z
    Transaction Hash : ca30a5cfa21b4006...
    asset_type       : "credit_alphanum4"
    asset_code       : "FUND"
    asset_issuer     : "GDWHBELCHNB6DQEICPDLVJMU3KQNFGE63I7WOMZW2KLTHZIHY5GPHIVG"
    limit            : "922337203685.4775807"

---

📁 Files Added / Modified

File	Change
lib/transactions.ts	NEW — getTransactionHistory(), getOperationHistory(), typed records, dep-injectable
tools/transactions.ts	NEW — StellarTransactionHistoryTool DynamicStructuredTool
agent.ts	MODIFY — add agent.transactions.getTransactions() and agent.transactions.getOperations()
index.ts	MODIFY — register tool in stellarTools[], export types
tests/unit/lib/transactions.test.ts	NEW — 17 unit tests
tests/unit/tools/transactions.test.ts	NEW — 12 unit tests

---

🧪 Test Coverage

• ✅ 17 lib-level tests (invalid key rejection, 404 handling, limit clamping, memo fields, empty results, mainnet URL, dependency injection)
• ✅ 12 tool-level tests (action delegation, output formatting, error surfacing, type re-exports)
• ✅ All 88 tests pass (29 new + 59 existing), zero regressions
• ✅ tsc --noEmit — zero TypeScript errors
• ✅ npm run build — clean production build verified in dist/

---

🛡️ Safety

• Strictly read-only — no transactions are constructed or signed
• No private key required for any operation
• No new dependencies — uses existing @stellar/stellar-sdk and @langchain/core
• Dependency-injectable server factory for full unit-testability without live network calls
• Friendly 404 error messages for unfunded or non-existent accounts
• Limit is clamped between 1 and 200 to prevent abuse

---

📎 Additional Context

The feature has been fully implemented, tested, and verified live on Stellar testnet.

• npm run build passes cleanly ✅
• npm test — 88/88 tests pass ✅
• tsc --noEmit — zero type errors ✅
• Live demo confirmed against real testnet data (payments, Soroban contract calls, trustlines) ✅

A PR is ready to be opened immediately once this issue is assigned.

---

Please assign me on this issue — I have already implemented this feature and it is fully working. The PR is ready to open. 🙏

---

🏷️ Suggested Labels

• enhancement
• feature
• good first review