Skip to content
Truto
Truto Blog
Back
AI & Agents

Connect Modulr to AI Agents: Orchestrate Full Fintech Workflows

Learn how to connect Modulr to ai agents using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows.

Sidharth Verma Sidharth Verma · · 10 min read
Connect Modulr to AI Agents: Orchestrate Full Fintech Workflows

You want to connect Modulr to an AI agent so your internal systems can independently execute payments, run Confirmation of Payee (CoP) checks, manage virtual cards, and handle complex KYB/KYC onboarding workflows based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually code dozens of endpoints or maintain complex API wrappers.

Giving a Large Language Model (LLM) read and write access to a regulated financial infrastructure platform like Modulr is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands the difference between a synchronous account lookup and an asynchronous batch payment, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Modulr to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Modulr to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

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

The Engineering Reality of Custom Modulr Connectors

Building AI agents is easy. Connecting them to external SaaS and fintech APIs is hard. Giving an LLM access to external data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production, this approach collapses entirely, especially with a strictly regulated ecosystem like Modulr.

If you decide to build the integration yourself, you own the entire API lifecycle. Modulr's API introduces several highly specific integration challenges that break standard LLM assumptions.

The Asynchronous Approval Trap

Unlike a simple CRM update, financial operations in Modulr are heavily regulated and often require multi-stage state machines. When an agent calls the endpoint to create a payment or batch payment, the Modulr API rarely returns a simple 200 OK with a finalized status. Instead, payments are processed asynchronously.

If you hand-code this integration, you have to write complex prompts to teach the LLM that a 202 Accepted response simply means the request is queued. Furthermore, payments might enter an APPROVAL_REQUIRED state if your Modulr account is configured for dual authorization. When the LLM inevitably assumes the payment is complete and attempts to notify a user or update an external ledger, you introduce massive reconciliation errors. The agent needs specific polling mechanisms or webhook integrations to verify that a payment transitions from EXTRACTED to PROCESSED.

Strict Idempotency and Nonce Rejection

LLMs are notoriously persistent. If a tool call fails due to a network timeout or a missing parameter, the agent will naturally attempt to call the tool again with the exact same payload.

In standard APIs, repeating a GET request is harmless. In Modulr, particularly with endpoints like Payer Name Verification (PNV) or Confirmation of Payee, the API enforces strict idempotency. Repeated use of a previously seen nonce will immediately return a 403 Forbidden. If your custom wrapper does not intercept the agent's retries and generate a fresh nonce for every single HTTP request, your agent will get trapped in an endless error loop, repeatedly throwing 403s until it exhausts its token limit.

The Complex Dependency Chain of Payments

You cannot simply ask an LLM to "charge this customer." Modulr enforces a strict relational hierarchy. To initiate a Variable Recurring Payment (VRP), for example, an agent cannot simply hit a charge endpoint. It must first query the customer, retrieve the authorized VRP consent using a specific ID, call the funds confirmation endpoint to ensure the account has sufficient liquidity, and only then initiate the payment initiation request. LLMs consistently fail at this multi-step orchestration if you just dump raw REST documentation into their system prompt.

Rate Limits: Handling 429s with Truto

When dealing with autonomous agents operating at scale, rate limiting is the most common point of failure. It is critical to understand exactly how Truto handles rate limits when proxying your agent's requests to Modulr.

Factual note: Truto does not automatically retry, throttle, or apply backoff on rate limit errors. When the upstream Modulr API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. However, because every SaaS provider formats rate limit information differently, Truto normalizes the upstream rate limit data into standardized headers based on the IETF specification:

  • ratelimit-limit: The total number of requests allowed in the current window.
  • ratelimit-remaining: The number of requests remaining in the current window.
  • ratelimit-reset: The time at which the rate limit window resets.

As the developer building the AI agent, you are responsible for reading these headers and instructing your agent or your execution loop to apply an appropriate backoff. Do not assume the infrastructure will magically absorb these errors - your agent loop must catch the 429, read the ratelimit-reset header, and pause execution.

Modulr Hero Tools for AI Agents

Truto exposes every resource in the Modulr API as an LLM-ready tool via the /tools endpoint. Instead of loading the entire API into the agent's context window - which causes severe hallucinations and token exhaustion - you can provide specifically scoped tools based on the agent's persona. Here are the hero tools most commonly used for fintech automation.

List All Modulr Accounts

list_all_modulr_accounts

Before an agent can initiate a transfer or check a balance, it needs the specific internal Modulr account ID. This tool allows the agent to filter accounts by customerId, currency, name, or balance range, returning a structured list of accounts and their current statuses.

"Find the active GBP operational account for customer ID 10934 and tell me the available balance before we initiate payroll."

Create a Modulr Account Name Check

create_a_modulr_account_name_check

Also known as Confirmation of Payee (CoP), this is a critical compliance tool. Before an agent generates a payment, it should run this check to verify that a payee's bank account details (sort code and account number) match their legal name. It returns the exact CoP match result (e.g., exact match, close match, no match) so the agent can autonomously decide whether to proceed or flag the transaction for human review.

"Run a Confirmation of Payee check for John Doe using sort code 12-34-56 and account number 12345678. If it returns an exact match, proceed to the next step."

Create a Modulr Payment

create_a_modulr_payment

This tool initiates a single Faster Payment to an external bank account or a transfer between internal Modulr accounts. The agent must provide the source account ID, destination details, amount, and currency. Because this is asynchronous, the agent must be instructed to monitor the resulting approval status.

"Initiate a payment of £500 from our GBP operating account to the beneficiary ID 88473. Use the reference 'Invoice-992' and confirm the returned payment ID."

Create a Modulr Batch Payment

create_a_modulr_batchpayment

For payroll processing or supplier payment runs, calling the single payment endpoint 500 times is inefficient and risks rate limiting. This tool allows the agent to submit an array of payment objects as a single batch request, returning a master id and a summary of the batch status.

"Take this list of 45 approved contractor invoices and submit them as a single batch payment from account ID 99283. Ensure the submission is set to strict mode so the entire batch fails if one record is malformed."

Get Single Modulr Payment by ID

get_single_modulr_payment_by_id

Because payment creations return asynchronous statuses, agents use this tool to poll or verify the outcome of a transaction. It returns the detailed object including status, approvalStatus, message, and any scheme-specific information.

"Check the status of payment ID P-109238. If the status is PROCESSED, draft a confirmation email to the supplier. If it is APPROVAL_REQUIRED, alert the finance manager on Slack."

Create a Modulr Customer

create_a_modulr_customer

Used by onboarding agents, this tool creates a new Modulr customer record. It requires complex nested objects depending on the customer type (e.g., corporate vs individual, director details, registered addresses). The agent can parse raw application data and construct the required JSON schema.

"We just received an approved application for a new corporate client, Acme Corp. Create a new Modulr customer record using their registered London address and set the default verification status to ACTIVE."

To view the complete inventory of available operations, request schemas, and available filters, visit the Modulr integration page.

Workflows in Action

Giving an agent isolated tools is only the first step. The true value lies in chaining these tools to execute multi-step operations that previously required human intervention or complex middleware.

Persona: FinOps Payment Orchestrator

This agent is tasked with safely executing supplier payments. It must ensure compliance rules are met before allowing funds to leave the ecosystem.

"I have an approved invoice for £1,200 payable to 'Tech Logistics Ltd' with sort code 20-30-40 and account 87654321. Please verify the payee and, if successful, execute the payment from our main operations account."

  1. Tool Call: list_all_modulr_accounts - The agent queries the system to find the ID of the "main operations account" and verifies it has a balance exceeding £1,200.
  2. Tool Call: create_a_modulr_account_name_check - The agent runs a Confirmation of Payee check against the provided sort code, account number, and string "Tech Logistics Ltd".
  3. Tool Call: create_a_modulr_payment - After receiving an "Exact Match" result from the name check, the agent structures the payment payload and executes the transfer.
  4. Tool Call: get_single_modulr_payment_by_id - The agent waits 5 seconds and checks the payment ID to confirm it moved from queued to PROCESSED.

Result: The agent successfully verified the counterparty risk and executed the payment without human intervention, returning a final transaction reference to the user.

Persona: Client Onboarding Specialist

This agent manages the provisioning of new accounts for an embedded finance platform, handling both the entity creation and the financial infrastructure setup.

"Onboard our new client, 'Global Retail Partners'. Create their customer record, then immediately provision three segregated accounts: one for GBP Collections, one for EUR Collections, and one for GBP Payouts."

  1. Tool Call: create_a_modulr_customer - The agent passes the corporate entity data to Modulr, securing a unique customerId.
  2. Tool Call: create_a_modulr_customer_account - The agent calls this tool three consecutive times using the new customerId. It sets the currency to GBP and names it "GBP Collections", then EUR for "EUR Collections", and finally GBP for "GBP Payouts".
  3. Tool Call: list_all_modulr_customer_accounts - The agent pulls the complete list of accounts for this specific customer to verify all three were successfully provisioned and to extract their newly generated IBANs/Account numbers.

Result: The user receives a structured summary containing the new Modulr customer ID alongside the three active account identifiers, ready to be sent to the client.

Building Multi-Step Workflows

To implement these autonomous loops, you must fetch the tool definitions from Truto and bind them to your LLM. Because Truto normalizes the Modulr API into standard JSON Schema, these tools are compatible with any modern AI framework.

The critical engineering challenge is handling Modulr's API constraints and Truto's rate limit pass-through. When building your agent executor, you must wrap tool invocations in a layer that catches 429 Too Many Requests errors, reads the IETF-standard ratelimit-reset header, and instructs the agent to yield or wait.

Here is how you structure this workflow using the Truto SDK and LangChain in TypeScript:

import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runFintechAgent() {
  // 1. Initialize the Truto Tool Manager with your Integrated Account ID for Modulr
  const toolManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY!,
    integratedAccountId: process.env.MODULR_ACCOUNT_ID!,
  });
 
  // 2. Fetch all Modulr proxy methods as LangChain-compatible tools
  const modulrTools = await toolManager.getTools();
 
  // 3. Initialize the LLM (e.g., GPT-4o for complex JSON structuring)
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 4. Bind the Modulr tools to the model
  const modelWithTools = llm.bindTools(modulrTools);
 
  // 5. Create the system prompt with strict fintech instructions
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", `You are an autonomous FinOps agent connected to Modulr.
    CRITICAL RULES:
    - ALWAYS run a Confirmation of Payee (create_a_modulr_account_name_check) before creating a payment.
    - If an API tool returns a 429 error, you MUST stop and wait for the time specified in the error message.
    - Do not invent account IDs. Always use list_all_modulr_accounts if you are missing an ID.`],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 6. Assemble the agent and executor
  const agent = createToolCallingAgent({
    llm: modelWithTools,
    tools: modulrTools,
    prompt,
  });
 
  const executor = new AgentExecutor({
    agent,
    tools: modulrTools,
    maxIterations: 10,
  });
 
  // 7. Execute a multi-step workflow
  try {
    const result = await executor.invoke({
      input: "Check the balance of our GBP operating account. If it is over 1000, verify the payee 'Widget Co' with sort code 12-34-56 and account 12345678. If the name check passes, send them 500 GBP."
    });
    console.log("Workflow Complete:", result.output);
  } catch (error) {
    // Implement rate limit catching here. 
    // Truto passes the 429 and standard headers back to the caller.
    if (error.status === 429) {
      const resetTime = error.headers['ratelimit-reset'];
      console.error(`Rate limited by Modulr. Window resets at: ${resetTime}. Backing off...`);
      // Implement your custom sleep/retry logic here based on resetTime
    } else {
      console.error("Agent execution failed:", error);
    }
  }
}
 
runFintechAgent();

The architectural flow of this system ensures that the agent handles decision-making while Truto handles the complex API proxying and schema normalization. Here is a visualization of how rate limits are passed through:

sequenceDiagram
    participant Agent as AI Agent
    participant TrutoSDK as Truto SDK
    participant ModulrAPI as Modulr API
    Agent->>TrutoSDK: Call create_a_modulr_account_name_check
    TrutoSDK->>ModulrAPI: POST /name-check
    ModulrAPI-->>TrutoSDK: 429 Too Many Requests
    TrutoSDK-->>Agent: Error (Check ratelimit-reset)
    Agent->>Agent: Wait for reset window
    Agent->>TrutoSDK: Retry request
    TrutoSDK->>ModulrAPI: POST /name-check
    ModulrAPI-->>TrutoSDK: 200 OK
    TrutoSDK-->>Agent: Payee Verified

By leveraging Truto to abstract the connection layer, you avoid writing thousands of lines of boilerplate code to handle Modulr's authentication, schema definitions, and endpoint mapping. The LLM simply sees a clean, documented tool interface.

If you want your AI agents to execute real-world financial operations securely and reliably, you must architect the system to respect the upstream API's constraints. Modulr is unforgiving when it comes to compliance, idempotency, and asynchronous states. By using Truto's /tools endpoint, you instantly provide your agent framework with the exact schemas and descriptions required to navigate this complexity without writing a single line of integration code.

More from our Blog