Connect Chimoney to AI Agents: Orchestrate Multi-Rail Disbursements

You want to connect Chimoney to an AI agent so your system can independently orchestrate global multi-rail disbursements, verify bank accounts in real-time, execute mobile money payouts, and manage agent wallet policies based on natural language commands or automated system events. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually map dozens of complex payment rails or maintain brittle API wrappers. For teams already using Truto to connect Dwolla to AI agents for domestic ACH, Chimoney provides the global expansion for that same orchestration logic.

Giving a Large Language Model (LLM) read and write access to a global financial infrastructure like Chimoney is a massive engineering undertaking. You either spend weeks building, hosting, and maintaining a custom connector that understands the distinct payload requirements of bank transfers versus Interac or mobile money, or you use a managed infrastructure layer that handles the abstraction for you. If your team uses ChatGPT, check out our guide on connecting Chimoney to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Chimoney 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 Chimoney, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex multi-country payout workflows. 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 Chimoney Connectors

Building AI agents is easy. Safely connecting them to external financial 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 an ecosystem as complex as global payouts. If you have previously tried to connect Stripe to AI agents, you likely encountered similar challenges with schema strictness and API lifecycle management.

If you decide to build a custom integration for Chimoney, you own the entire API lifecycle. Chimoney's API introduces several specific integration challenges that break standard LLM assumptions and require rigid orchestration logic.

The Multi-Rail Schema Fragmentation

Unlike standard SaaS CRUD APIs where a User object is universally understood, Chimoney is an orchestration layer for multiple distinct financial networks (rails). A payout is not just a standard POST /payouts with an amount and an email. The payload shape shifts entirely depending on the destination rail.

For example, if an AI agent decides to execute a bank payout to a recipient in Kenya, it must formulate a payload containing account_bank, account_number, and potentially a branch_code. If that same agent decides to execute a Mobile Money (Momo) payout to a recipient in Ghana, the payload completely changes - it now requires countryToSend, phoneNumber, valueInUSD, and a specific momoCode. If you hand-code this integration, you have to write incredibly complex, context-heavy system prompts to teach the LLM the exact JSON schema required for every single country and payment method combination. When the LLM hallucinations a branch_code onto a mobile money payout, the Chimoney API will reject it.

Mandatory Pre-Validation Chains

Financial APIs do not tolerate "guess and check" operations. You cannot simply instruct an AI to "send 50 dollars to John's account at Zenith Bank." The agent must traverse a strict sequence of pre-validation API calls before execution.

First, the agent must query the list of supported banks for the target country to get the exact bank_code. Second, it often needs to fetch the specific branch_code. Third, and most critically, it must execute a pre-flight verification against the bank account using the account number and bank code to ensure the account holder name matches the intended recipient. Only after this chain of successful validations can the actual disbursement be triggered. Teaching an LLM this mandatory sequence through custom code requires complex state management and rigid guardrails.

Asynchronous State and Issue IDs

When a payout is successfully initiated in Chimoney, the funds do not always instantly arrive at the destination. The API returns an asynchronous reference, typically a chiRef or an issueID.

If an agent is tasked with "paying a vendor and confirming receipt," it must understand that the initial 200 OK from the payout endpoint only means the transaction was queued. The agent must then know how to store that chiRef, suspend its operation, and periodically poll the payout status endpoint to verify the terminal state (e.g., paid, failed, or fraud). Custom wrappers require you to build durable execution loops to handle these asynchronous state checks.

Architecting the AI-to-Chimoney Bridge

To solve this, Truto maps Chimoney's complex, multi-rail API into standardized Proxy APIs. Every endpoint on the underlying Chimoney API is mapped to a Resource with defined Methods (List, Get, Create, Update, Delete, or Custom).

Instead of teaching your LLM the nuances of Chimoney's REST implementation, Truto provides a set of tool definitions complete with descriptions and JSON schemas for all available Methods. You call the /integrated-account/:id/tools endpoint, and Truto returns a framework-ready array of tools. The LLM simply calls the tool, and Truto handles the underlying authentication, parameter processing, and HTTP execution.

A Crucial Note on Rate Limits and Backoff

When exposing financial APIs to autonomous agents, you must architect for rate limits. Agents operate at computer speed, and aggressive loops can quickly exhaust API quotas.

It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Chimoney API returns an HTTP 429 (Too Many Requests), Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification.

The caller (your agent framework or application logic) is strictly responsible for inspecting these headers, implementing retry logic, and applying exponential backoff. Do not design your system assuming Truto will automatically absorb or queue rate-limited requests.

sequenceDiagram
    participant Agent as "AI Agent Loop"
    participant Truto as "Truto Tools API"
    participant Upstream as "Chimoney API"

    Agent->>Truto: Call tool: create_a_chimoney_payouts_bank
    Truto->>Upstream: POST /payouts/bank
    Upstream-->>Truto: 429 Too Many Requests<br>(X-RateLimit-Reset: 1710000000)
    Truto-->>Agent: 429 Error with IETF standardized headers
    Note over Agent: Agent logic reads ratelimit-reset<br>and suspends execution.

Building Multi-Step Workflows

To build autonomous workflows, you need to fetch the Chimoney tools from Truto and bind them to your LLM. Because Truto's /tools endpoint returns standard JSON Schema, this approach works natively with LangChain, LangGraph, Vercel AI SDK, or CrewAI - it is entirely framework-agnostic and not locked to a specific MCP (Model Context Protocol) implementation.

Below is a TypeScript example using the truto-langchainjs-toolset to fetch Chimoney tools and set up an agent loop capable of chaining multiple API calls together.

import { TrutoToolManager } from "@trutohq/langchainjs-toolset";
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
 
async function runChimoneyAgent() {
  // 1. Initialize the Truto Tool Manager with your Chimoney Integrated Account ID
  const toolManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY!,
    integratedAccountId: "chimoney_account_12345",
  });
 
  // 2. Fetch all available Chimoney tools dynamically
  const tools = await toolManager.getTools();
  console.log(`Loaded ${tools.length} Chimoney tools.`);
 
  // 3. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // 4. Create the system prompt with strict instructions for financial operations
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a financial operations agent connected to Chimoney. Always verify bank accounts before initiating bank payouts. If you receive a rate limit error, halt operations and report the reset time. Never guess branch codes."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 5. Bind tools to the agent
  const agent = await createOpenAIToolsAgent({
    llm,
    tools,
    prompt,
  });
 
  const executor = new AgentExecutor({
    agent,
    tools,
    handleParsingErrors: true,
    maxIterations: 10,
  });
 
  // 6. Execute a complex, multi-step financial request
  try {
    const result = await executor.invoke({
      input: "Verify the Nigerian bank account 0123456789 at bank code 058. If the name matches 'Jane Doe', execute a 50 USD payout to that account and give me the reference ID."
    });
    console.log(result.output);
  } catch (error: any) {
    // Handle HTTP 429 passthrough from Truto
    if (error.status === 429) {
      const resetTime = error.headers['ratelimit-reset'];
      console.error(`Rate limited by Chimoney. Agent paused until ${resetTime}`);
    } else {
      console.error("Workflow failed:", error);
    }
  }
}
 
runChimoneyAgent();

In this setup, the LLM determines which tools to call and in what order. It will automatically call the verification tool, parse the result, and if the condition passes, subsequently call the bank payout tool.

Hero Tools for Chimoney Operations

Truto exposes dozens of Chimoney endpoints as tools. When building financial agents, these are the highest-leverage tools that unlock end-to-end autonomous disbursements.

Verify Bank Account Number

Tool Name: create_a_chimoney_info_verify_bank_account_number

Before an agent can safely dispatch funds, it must verify the destination account. This tool takes a country code, bank code, and account number, and returns the registered account name. This is a mandatory safety check in any autonomous payout workflow.

"I need to run a verification on account number 1234567890 at bank code 044 in Nigeria. Tell me the exact account name returned by the bank so I can verify it against our contractor ledger."

Create a Bank Payout

Tool Name: create_a_chimoney_payouts_bank

This is the core tool for executing cross-border bank transfers. It accepts an array of payout objects containing the destination country, bank, account number, and USD value. The agent must ensure it has successfully retrieved required fields like branch_code (if outside Nigeria) before executing this tool.

"The account belongs to John Smith. Proceed with the bank payout of 500 USD to this verified account in Kenya. Ensure you include the branch code we fetched earlier. Return the chiRef of the transaction."

Create a Mobile Money Payout

Tool Name: create_a_chimoney_payouts_mobile_money

Mobile Money is an entirely distinct rail from traditional banking. This tool routes funds to mobile wallets across Africa and emerging markets. It requires the agent to provide the recipient's phone number, USD value, and the specific momoCode for the provider (e.g., MTN, MPESA).

"We need to disburse the 50 USD bounty via Mobile Money to the phone number +233541234567 in Ghana. Use the MTN momoCode and execute the payout."

Check Payout Status

Tool Name: create_a_chimoney_payouts_status

Because financial transactions are asynchronous, an agent needs a way to confirm terminal states. This tool allows the agent to submit a chiRef (the transaction reference) and retrieve the real-time processing status from the network.

"Take the chiRef 987654321 from our last transaction and check its status. Do not mark the ticket as resolved unless the status returns as 'paid'."

List Exchange Rates

Tool Name: list_all_chimoney_info_exchange_rates

Agents orchestrating global payouts need to understand currency conversion to plan budgets. This tool returns the current currency pair rates (e.g., NGNUSD) along with their exact expiration timestamps, allowing the agent to calculate local currency equivalents before funding.

"Check the current exchange rate for USD to NGN. How much local currency will the contractor receive if we send 1,000 USD right now? Make sure the rate hasn't expired."

Update AI Agent Policies

Tool Name: chimoney_agents_update_policies

Chimoney has native concepts of "AI Agents" with their own wallets. This tool allows your overarching orchestrator LLM to modify the compliance policies of subordinate Chimoney agents - such as altering daily spending limits, setting per-transaction caps, or adjusting recipient allowlists based on system risk signals.

"Update the compliance policy for our subordinate refund agent ID 555. Reduce its daily spending limit to 200 USD and restrict its payouts strictly to verified Interac emails."

For the complete inventory of available tools, required JSON schemas, and parameter constraints, visit the Chimoney integration page.

Workflows in Action

By chaining these tools together, developers can transition from building simple chat interfaces to deploying autonomous financial operators that execute complex, multi-step logic safely.

Use Case 1: Automated Multi-Country Payroll Disbursement

Managing contractor payouts across different continents requires routing payments through the most efficient rail per country. Instead of building a massive switch statement in your application code, an AI agent can dynamically route the funds and connect QuickBooks to AI agents to ensure every international disbursement is instantly recorded in your books.

"Run payroll for the three contractors in the attached manifest. Contractor A is in Nigeria (Bank transfer), Contractor B is in Ghana (Mobile Money), and Contractor C is in Canada. Validate their details, estimate the fees, and execute the payouts using the appropriate rails for each region. Give me a summary of all transaction references."

Step-by-Step Execution:

1. The agent calls list_all_chimoney_info_bank_branches and create_a_chimoney_info_verify_bank_account_number to validate Contractor A's Nigerian bank details.
2. The agent calls list_all_chimoney_info_mobile_money_codes to find the correct momoCode for Contractor B's provider in Ghana.
3. The agent calls create_a_chimoney_info_fee_estimate to calculate the total deduction required from the main wallet.
4. The agent executes create_a_chimoney_payouts_bank for Contractor A, create_a_chimoney_payouts_mobile_money for Contractor B, and create_a_chimoney_payouts_interac for Contractor C.

Result: The user receives a unified summary detailing the total USD spent, the estimated local currency received by each contractor, and the three distinct chiRef IDs for tracking, all handled without custom routing logic.

Use Case 2: Autonomous Refund and Wallet Top-Up

Customer support systems often need to issue localized refunds, but doing so requires ensuring the system has sufficient funds and the recipient's details are pristine.

"Customer ticket #445 requires a 25 USD refund to their UK bank account. Check our main wallet balance. If we have enough funds, verify the customer's sort code and account number provided in the ticket, and initiate the payout. If we don't have funds, alert the finance channel instead."

Step-by-Step Execution:

1. The agent calls list_all_chimoney_wallets to inspect the available USD balance.
2. Assuming sufficient funds, the agent calls create_a_chimoney_info_verify_bank_account_number using the customer's provided UK account details.
3. Upon successful verification, it calls create_a_chimoney_payouts_bank targeting the UK rail.
4. The agent stores the resulting chiRef and can optionally loop back to check create_a_chimoney_payouts_status to ensure it cleared.

Result: The customer support representative receives a confirmation that the refund was executed, completely bypassing the manual finance team approval queue, protected by immutable account verification guardrails.

Next Steps

Integrating AI with financial rails requires precision, standardized schemas, and a deep respect for external API constraints. By leveraging Truto's /tools endpoint, you offload the massive burden of maintaining dozens of fragmented payment rail schemas and focus entirely on designing the logic and guardrails of your agent.

Whether you are building a global payroll copilot, an automated treasury manager, or an autonomous refund system, treating the API integration as configuration rather than code is the only way to scale.