@sperax/tool-flash-loan-scanner
v0.2.1
Published
Scan DeFi protocols for flash loan arbitrage opportunities, liquidation targets, and multi-hop profit paths with real-time profitability analysis — an agent tool for SperaxOS.
Maintainers
Readme
@sperax/tool-flash-loan-scanner
Scan DeFi protocols for flash loan arbitrage opportunities, liquidation targets, and multi-hop profit paths with real-time profitability analysis
Flash Loan Scanner is an agent tool from SperaxOS, packaged headless so you can call
it from any agent framework. It ships two things: the manifest — a JSON-Schema function
definition a model can call — and the executor that runs the call against the real API.
There is no UI layer and no framework lock-in. It works anywhere TypeScript runs.
Install
npm install @sperax/tool-flash-loan-scannerUsage
Call it directly
import { flashLoanScannerExecutor } from '@sperax/tool-flash-loan-scanner';
const result = await flashLoanScannerExecutor.invoke('scanArbitrageOpportunities', {"chains":"<chains>","includeCrossChain":"<includeCrossChain>"}, {
messageId: 'msg-1',
});
console.log(result.content); // prose summary written for the model to read
console.log(result.state); // typed data payload for your own UIGive it to a model
import Anthropic from '@anthropic-ai/sdk';
import { FlashLoanScannerManifest, flashLoanScannerExecutor } from '@sperax/tool-flash-loan-scanner';
const client = new Anthropic();
const response = await client.messages.create({
model: 'claude-opus-4-8',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Ask something this tool can answer' }],
tools: FlashLoanScannerManifest.api.map((api) => ({
name: api.name,
description: api.description,
input_schema: api.parameters,
})),
});
for (const block of response.content) {
if (block.type !== 'tool_use') continue;
const result = await flashLoanScannerExecutor.invoke(block.name, block.input, { messageId: response.id });
console.log(result.content);
}FlashLoanScannerManifest.api is already in JSON-Schema form, so it maps onto any tool-calling API —
Anthropic, OpenAI, the Vercel AI SDK, or an MCP server — without translation.
Every executor returns a BuiltinToolResult — { success, content, state }. content is
prose written for the model to read; state is the typed data payload for your own code.
Executors never throw: a failed call comes back as { success: false, content: '<reason>' },
so a network blip degrades the answer instead of crashing the agent loop.
Configuration
None. This tool calls a public API directly and needs no key or origin configuration.
Tool identifier
sperax-flash-loan-scanner
API reference
scanArbitrageOpportunities
Scan DEXes for real-time arbitrage opportunities. Detects price discrepancies across multiple DEXes and chains, calculates net profitability after gas and flash loan fees.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chains | array | no | Chains to scan (e.g. ["ethereum", "arbitrum"]). Default: all major chains. |
| includeCrossChain | boolean | no | Include cross-chain arbitrage opportunities. Default: false. |
| maxHops | number | no | Maximum hops in multi-hop arb. Default: 3. |
| minConfidence | number | no | Minimum confidence score (0-100). Default: 50. |
| minProfitUsd | number | yes | Minimum net profit threshold in USD. |
| tokens | array | no | Specific tokens to scan. Use "top50" for top tokens by volume. |
findLiquidationTargets
Find lending protocol positions near liquidation. Monitors health factors and calculates potential liquidation profits.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chains | array | no | Chains to scan. |
| maxHealthFactor | number | yes | Maximum health factor to consider (e.g. 1.1 for positions near liquidation). |
| minProfitUsd | number | yes | Minimum profit threshold in USD. |
| onlyLiquidatable | boolean | no | Only show positions that are currently liquidatable. Default: false. |
| protocols | array | no | Lending protocols to scan (e.g. ["aave", "compound"]). |
estimateFlashLoanProfit
Estimate exact profitability of a flash loan opportunity. Calculates all costs (gas, flash loan fee, slippage) and shows step-by-step execution plan.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| loanAmountUsd | number | yes | Flash loan amount in USD. |
| opportunityId | string | no | Opportunity ID from scan results. |
| preferredProvider | string | no | Preferred flash loan provider (aave, dydx, balancer, etc.). |
getFlashLoanProviders
Compare flash loan providers. Shows fees, available liquidity, supported tokens, and recommendations.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chain | string | yes | Chain to query. |
| minAmountUsd | number | no | Minimum borrowable amount needed. |
| token | string | no | Specific token to borrow. |
analyzeHistoricalFlashLoans
Analyze historical flash loan activity on a chain. Shows trends in profitability, common strategies, and success rates.
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| chain | string | yes | Chain to analyze. |
| limit | number | no | Maximum number of results. Default: 50. |
| minProfitUsd | number | no | Minimum profit filter. |
| periodDays | number | yes | Historical period in days. |
| type | string | no | Filter by type: "arbitrage", "liquidation", or "all". |
Types
Shared types come from @sperax/agent-tools-core:
BuiltinToolManifest, BuiltinToolResult, BuiltinToolContext, and the BaseExecutor
class every tool executor extends.
Related
@sperax/agent-tools-core— the tool contract- All SperaxOS agent tools — tool-flash-loan-scanner is one of many
- SperaxOS — the agent workspace these tools were built for
License
Apache-2.0
