Connect Orum to AI Agents: Sync Subledgers and Financial Reports

You want to connect Orum to an AI agent so your system can autonomously onboard customers, verify bank accounts, issue payouts, and reconcile financial subledgers. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom Orum integration from scratch.

Giving a Large Language Model (LLM) read and write access to a core banking and money movement API is an exercise in extreme precision. When AI interacts with financial rails, it cannot hallucinate idempotency keys, guess at ledger IDs, or misunderstand asynchronous transfer states. If your team uses ChatGPT, check out our guide on connecting Orum to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Orum to Claude. For developers building custom autonomous workflows, you need a programmatic, deterministic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Orum, bind them natively to an LLM using LangChain (or frameworks like LangGraph, CrewAI, and the Vercel AI SDK), and execute complex financial operations. This approach is completely framework-agnostic. For a deeper look at the architecture behind this tool-calling pattern, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of the Orum API

Building an integration with Orum is fundamentally different from integrating a CRM or a ticketing system. Money movement APIs are unforgiving. If you hardcode API requests into your agent's prompts or rely on basic REST wrappers, you will spend your engineering cycles writing defensive code rather than improving your model's reasoning.

The Orum API introduces specific architectural challenges that break standard LLM assumptions:

1. Strict Reference ID Idempotency

Orum relies heavily on client-generated reference IDs (customer_reference_id, transfer_reference_id, account_reference_id). This acts as an idempotency layer to prevent double-charging or duplicate account creation. Standard LLMs are notoriously bad at consistently passing the same client-generated UUID across multiple turns of a conversation unless strictly forced. Furthermore, Orum strictly enforces that closed entities cannot have their reference IDs reused. If an agent closes a business account, it cannot simply "re-create" it using the same customer_reference_id - a nuance that models easily trip over.

2. Asynchronous State Transitions

In Orum, initiating a transfer or verifying an account does not immediately yield a terminal state. When you call the transfer API, the response is typically a pending status. LLMs are eager; they assume a 2xx HTTP response means the money has moved. An agent must be programmed to poll or interpret status_reasons and transfer_history to confirm whether a transfer failed due to insufficient funds, ACH return codes, or risk flags. Failing to map this async reality into a synchronous tool-calling loop results in agents confidently hallucinating that payments are complete when they are actually stuck in processing.

3. The Strict Resource Hierarchy

Orum enforces a rigid resource hierarchy. To move money, an agent must traverse a precise dependency graph: create a Person/Business -> create an External Account -> verify the account -> initiate a Transfer. If you expose raw endpoints to an LLM, it will frequently attempt to initiate a transfer before the external account is fully verified, leading to 400 Bad Request errors. The tool layer must enforce this schema strictly.

Why a Unified Tool Layer Matters for Financial Agents

Directly wrapping raw Orum endpoints pushes all of the above quirks into your LLM's context window. You are forcing the model to act as a FinTech engineer.

Truto solves this by providing Proxy APIs mapped directly to Orum's endpoints, accessible via the /tools endpoint. Truto handles the authentication, payload structuring, and query parameter processing, exposing a deterministic JSON schema to the LLM.

A Crucial Note on Rate Limits

When dealing with money movement, pacing is critical. It is a factual engineering reality that Truto does not retry, throttle, or apply backoff on rate limit errors. When the Orum API returns an HTTP 429 Too Many Requests, Truto passes that 429 error directly back to the caller.

However, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). Your agent's execution loop is fully responsible for reading these headers, pausing execution, and applying backoff. This prevents Truto from masking latency or creating race conditions in your financial workflows.

flowchart TD
    A["Agent Execution Loop"] -->|"Tool Call: create_a_orum_deliver_transfer"| B["Truto /tools Endpoint"]
    B -->|"Normalized payload + Auth"| C["Orum Deliver API"]
    C -->|"HTTP 429 Rate Limit"| B
    B -->|"Passes 429 + ratelimit headers"| A
    A -->|"Sleep / Backoff"| A

Hero Tools for Orum AI Agents

Instead of overwhelming the agent with dozens of edge-case endpoints, you should expose high-leverage "hero tools." Truto's tools are generated from Orum's resource methods, complete with strictly typed JSON schemas.

Here are the critical tools for building an Orum AI Agent.

1. Bank Account Verification

Tool Name: create_a_orum_verify_account

Before you can move money, you must verify the external bank account. This tool allows the agent to submit routing and account numbers to Orum's Verify engine to determine ownership, control, and debit status.

"The vendor provided routing number 021000021 and account number 123456789. Submit these details to Orum Verify to confirm debit status. If verification fails, stop the workflow and alert me."

2. Customer Onboarding (Person)

Tool Name: create_a_orum_deliver_person

This tool creates a human customer in Orum Deliver. The agent must provide a unique customer_reference_id, first name, and last name. This is the foundational node in the Orum resource hierarchy for consumer transactions.

"Onboard Jane Doe into the system. Generate a new unique UUID for her customer_reference_id. Do not reuse any previously failed reference IDs."

3. External Account Linking

Tool Name: create_a_orum_external_account

Once a Person or Business is created, this tool attaches a verified bank account to that entity. The agent must map the customer_reference_id from the previous step to the new account_reference_id.

"Link the verified Chase checking account to the business entity Acme Corp. Use the legal name exactly as returned from the verification step."

4. Virtual Ledger Creation

Tool Name: create_a_orum_deliver_subledger

Subledgers represent separate pools of funds attached to an existing customer. This tool allows the agent to create programmatic wallets for users, enabling complex marketplace or escrow flows.

"Create a new subledger for customer ID 8f7e6d5c. Label this subledger as their 'escrow reserve' and retrieve the new subledger ID."

5. Money Movement

Tool Name: create_a_orum_deliver_transfer

This is the core execution tool. It initiates a transfer between a source and destination party. The agent must supply the amount, currency, and desired speed (e.g., RTP, FedNow, Same Day ACH).

"Initiate a transfer of 1500 USD from the master operating account to vendor ID 443322. Use Same Day ACH for the speed. Generate a unique transfer_reference_id."

6. Transaction Status Auditing

Tool Name: orum_deliver_transfers_get_transfer_history

Because transfers are asynchronous, this tool is required for agents to check the status of a payment. It returns the history of status changes, exposing critical failure reasons like ACH returns or network timeouts.

"Check the history for transfer ID trf_998877. If the status is returned or failed, extract the status_reason and draft an email to the vendor explaining the issue."

7. Financial Reporting

Tool Name: list_all_orum_reports_balances

Agents need context to make financial decisions. This tool fetches a balance statement summary report for a requested date range, allowing the agent to verify sufficient funds before executing bulk payouts.

"Pull the balance report for the last 7 days. Calculate the total available liquidity across all subledgers and confirm we have at least 50000 USD before processing the payout run."

To view the complete inventory of available Orum tools, including Webhooks, Deliver Cards, and Business endpoints, check out the Orum integration page.

Building Multi-Step Workflows

To build an autonomous agent, you need to pull these tool schemas from Truto and bind them to your LLM. Using the Truto SDK (truto-langchainjs-toolset), this process is streamlined. The following example demonstrates a LangChain setup, but the JSON schemas returned by Truto's /tools endpoint work seamlessly with LangGraph, CrewAI, and the Vercel AI SDK.

First, fetch the Orum tools and bind them to an OpenAI model:

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { HumanMessage } from "@langchain/core/messages";
 
async function initializeOrumAgent() {
  // Initialize the tool manager with your Truto environment details
  const trutoManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
    environment: "production"
  });
 
  // Fetch tools for the specific Orum integrated account ID
  const orumAccountId = "orum_acc_01XYZ";
  const tools = await trutoManager.getToolsForAccount(orumAccountId);
 
  // Filter for the hero tools we need in this workflow
  const agentTools = tools.filter(tool => 
    ["create_a_orum_deliver_person", "create_a_orum_external_account", "create_a_orum_deliver_transfer"].includes(tool.name)
  );
 
  // Bind the tools to the LLM
  const llm = new ChatOpenAI({ 
    modelName: "gpt-4o", 
    temperature: 0 
  }).bindTools(agentTools);
 
  return { llm, agentTools };
}

When building the execution loop, you must account for Truto's rate limit behavior. Truto passes the Orum 429 errors directly to you, meaning your agent framework or calling code must catch this and back off.

async function executeAgentWorkflow(prompt: string) {
  const { llm, agentTools } = await initializeOrumAgent();
  const messages = [new HumanMessage(prompt)];
  
  let retries = 0;
  const maxRetries = 3;
 
  while (true) {
    try {
      const response = await llm.invoke(messages);
      messages.push(response);
 
      if (response.tool_calls && response.tool_calls.length > 0) {
        for (const toolCall of response.tool_calls) {
          const tool = agentTools.find(t => t.name === toolCall.name);
          if (tool) {
            // Execute the tool call against Truto's proxy API
            const toolResult = await tool.invoke(toolCall.args);
            messages.push({ 
              role: "tool", 
              tool_call_id: toolCall.id, 
              content: JSON.stringify(toolResult) 
            });
          }
        }
      } else {
        // No more tool calls, workflow is complete
        return response.content;
      }
    } catch (error: any) {
      // Explicitly handle 429 Rate Limits from Truto/Orum
      if (error.response && error.response.status === 429) {
        const resetTime = error.response.headers['ratelimit-reset'];
        const sleepTime = resetTime ? (parseInt(resetTime) * 1000) : 5000;
        
        if (retries >= maxRetries) {
          throw new Error("Max rate limit retries exceeded.");
        }
        
        console.warn(`Rate limited by upstream. Sleeping for ${sleepTime}ms...`);
        await new Promise(resolve => setTimeout(resolve, sleepTime));
        retries++;
      } else {
        throw error;
      }
    }
  }
}

Workflows in Action

When you equip an agent with these Orum tools, you move beyond simple API wrappers and enable autonomous FinTech operations. Here are two real-world examples of how this architecture behaves in production.

Scenario 1: Autonomous Vendor Onboarding and Verification

A marketplace application needs to onboard a new vendor, verify their banking details, and prepare their account to receive payouts.

"We have a new vendor, 'Apex Logistics'. Their routing number is 122000661 and account is 99887766. Create a business profile for them, verify the bank details, and if the account is cleared for push payments, link it to their profile."

Agent Execution Steps:

1. Tool Call: create_a_orum_deliver_business - The agent generates a UUID for customer_reference_id and creates the entity for "Apex Logistics".
2. Tool Call: create_a_orum_verify_account - The agent submits the routing and account number. Orum returns a verification status indicating the account is active and owned by the vendor.
3. Tool Call: create_a_orum_external_account - Seeing the positive verification, the agent uses the customer_reference_id from Step 1 to attach the verified account details to the business profile.

Outcome: The system responds confirming the vendor is fully onboarded and the ledger is ready for future transfers, without a human writing a multi-step verification script.

Scenario 2: Automated Subledger Reconciliation and Payouts

At the end of the month, a platform needs to check its master balance, verify contractor subledgers, and issue payouts.

"Pull our balance report for this week. If our master account has over $100,000, create a new subledger for contractor ID cont_992, and initiate a $2,500 Same Day ACH transfer to their linked external account. Generate a unique reference ID for the transfer."

Agent Execution Steps:

1. Tool Call: list_all_orum_reports_balances - The agent pulls the financial report, parses the JSON response, and confirms the available liquidity exceeds the $100,000 threshold.
2. Tool Call: create_a_orum_deliver_subledger - The agent creates a specific pool of funds for the contractor, using their existing ID.
3. Tool Call: create_a_orum_deliver_transfer - The agent initiates the $2,500 transfer using the speed parameter set to "same_day_ach" and generating a fresh UUID for the transfer_reference_id.

Outcome: The agent safely verifies liquidity, segregates funds logically, and initiates the payment. If the balance check had failed, the agent would have skipped the transfer and alerted the operations team.

sequenceDiagram
    participant Agent as AI Agent
    participant Truto as Truto Tool Layer
    participant Orum as Orum API
    Agent->>Truto: list_all_orum_reports_balances
    Truto->>Orum: GET /reports/balances
    Orum-->>Truto: Balance: $150,000
    Truto-->>Agent: Balance: $150,000
    Note over Agent: Condition met (> $100k)
    Agent->>Truto: create_a_orum_deliver_transfer
    Truto->>Orum: POST /transfers
    Orum-->>Truto: Status: Pending
    Truto-->>Agent: Status: Pending

Moving Beyond REST Wrappers

Building FinTech integrations with AI agents is not about writing fetch requests; it is about providing a safe, bounded, and strict tool layer. Exposing raw Orum endpoints to an LLM introduces hallucination risks regarding idempotency keys, asynchronous state, and strict resource hierarchies.

By utilizing Truto's /tools endpoint, you collapse the complexity of the Orum API into a standardized, machine-readable schema. Your engineering team can focus on refining the agent's prompts and financial logic, while Truto handles the execution, schema generation, and normalization of rate limit headers.