Fundline Documentation

Architecture

How Fundline works

Fundline separates invoice creation, payment execution and payment verification. The app never holds customer funds. The settlement routers transfer USDC directly from the payer wallet to the recipient wallet.

Quick start

From invoice to paid status

1. Connect your wallet.Go to fundline.xyz/app and connect an EVM wallet. The connected address becomes your USDC receiving wallet.
2. Create an invoice.Add client name, due date, and line items. Fundline calculates the USDC total and saves the invoice.
3. Send the payment link.Copy the fundline.xyz/pay/:invoiceId link and send it to your client by email, chat, or any channel.
4. Client pays.The client opens the link and pays in USDC from Arc, Base, or Ethereum. No account needed on their side.
5. Fundline confirms on-chain.Fundline verifies the transaction on Arc. Once confirmed, the invoice status changes to paid and the money is in your wallet.
6. Receive your alert and receipt.A Telegram notification fires and a PDF receipt is available on the invoice page.

Wallet setup

Merchant and payer wallets

The merchant must sign in before creating invoices. This signature proves wallet control and fills the receiving wallet automatically. Payers only need to connect when they want to pay directly through the app. If they pay outside the app, they can paste the payer wallet and transaction hash for verification.

Product

Create invoice

An invoice contains client name, client email, due date, note and line items.

Payment

On-chain payment flow

On the public payment page the payer approves the exact USDC amount, then calls the settlement router (FundlineMemoRouter) with payInvoice(bytes32,address,uint256). A repeat payer who already approved enough allowance pays in a single transaction.

payInvoice(bytes32 invoiceId, address merchant, uint256 amount)

A payer who does not connect a wallet can still send USDC directly and verify the transfer. On Arc, where USDC is the gas token, the payment-page QR uses an EIP-681 native transfer URI so exchange and mobile wallets can scan and pay without importing a token contract.

On-chain memo

Optional on-chain invoice memo

FundlineMemoRouter can record selected invoice details on the payment transaction itself as a public, permanent memo, emitted in an InvoiceMemo event. It is opt-in per invoice: the merchant chooses which fields to publish, with a clear warning for sensitive fields such as the client name.

For verifiable records without revealing content, the memo can instead carry a SHA-256 commitment of the invoice. The memo is a log only, never stored in contract state, and capped in size.

payInvoiceWithMemo(bytes32 invoiceId, address merchant, uint256 amount, bytes memo)

Receipts

PDF receipt and Excel export

Paid invoices can generate a professional PDF receipt. The receipt includes invoice number, payer wallet, receiving wallet, transaction hash, verification source and paid timestamp. Merchants can also export a styled Excel workbook (.xls) from the dashboard: gold header row, status-coloured cells (green for paid, amber for open, red for overdue), and zebra-row shading for easy bookkeeping.

Telegram

Run invoicing from Telegram

Telegram is a first-class surface, not only an alert channel. A merchant can create an invoice directly inside a chat through a guided flow (client, amount, due date, confirm), then share the payment link. The bot uses long polling, so no public webhook endpoint is required.

The link between a Telegram chat and a merchant wallet is a confirmed one-to-one binding. It is created as pending from the signature-verified settings write, and only becomes active when that same chat sends /start. This stops anyone from pasting someone else's chat ID to capture their alerts. Invoices created from the bot always use the linked wallet as the receiving wallet.

When a payment is verified, Fundline sends an instant message with the invoice number, amount, payer wallet, receiving wallet and transaction link. Alerts are dispatched server-side, so they do not depend on the merchant having a browser open.

TELEGRAM_BOT_TOKEN=replace_with_telegram_bot_token

Settlement

Cross-chain settlement via CCTP

Payers on Ethereum Sepolia or Base Sepolia can pay an Arc invoice without bridging manually. Fundline starts a CCTP fast-transfer flow: approve Circle's TokenMessengerV2, burn source USDC, fetch the attestation from the IRIS API, mint native USDC on Arc, then pay the invoice through FundlineMemoRouter. The whole flow completes in roughly 30 to 60 seconds at the Fast finality tier.

TokenMessengerV2=0x8FE6B999Dc680CcFDD5Bf7EB0974218be2542DAA
MessageTransmitterV2=0xE737e5cEBEEBa77EFE34D4aa090756590b1CE275

The payment page lets payers choose the network where they already hold USDC. Arc USDC pays directly. If the payer chooses Base Sepolia or Ethereum Sepolia and the balance is sufficient, Fundline starts a bridge-and-pay flow: approve TokenMessengerV2, burn source USDC, fetch Circle attestation, mint on Arc, then pay the invoice through the settlement router.

Arc payers who already hold USDC on Arc pay directly in a single transaction without any bridging step.

Bulk payout

Payroll and batch payouts

FundlineBatchRouter settles a one-to-many payout in a single transaction: payroll, speaker fees, or refunds. The merchant uploads a CSV of recipients (name, wallet, amount, optional reference), Fundline mints one payout link, and the payer settles everyone at once. The payer approves the total once, then a single call distributes USDC from the payer directly to each recipient.

A batch is atomic: if any single transfer fails, the whole transaction reverts, so a payroll run can never be left half paid. Like the invoice router, it is non-custodial and holds no balance. An optional per-recipient memo can record each reference (for example a payslip note) on-chain.

payBatch(bytes32 batchId, address[] recipients, uint256[] amounts)
payBatchWithMemo(bytes32 batchId, address[] recipients, uint256[] amounts, bytes[] memos)

AI Workflows

Multi-step AI workflows with per-run billing

AI Workflows run proven, multi-step chains of language model calls and live web search to produce a finished deliverable. Each workflow runs server-side; you see every step, model, and cost before and after the run. Billing is per run in USDC through the non-custodial FundlineRunEscrow contract.

How a run works: connect your wallet, click Run, approve USDC if needed, sign a fund(runId, amount) call to lock the fixed price into escrow. The server verifies the on-chain funding, executes the workflow chain, then the treasury key signs release(runId) on success (with an on-chain memo in the same format as FundlineMemoRouter). If the run fails at any step, the treasury signs refund(runId) and the USDC returns to your wallet.

fund(bytes32 runId, uint256 amount)
release(bytes32 runId, bytes memo)
refund(bytes32 runId)
claimRefund(bytes32 runId)  // user backstop after 1h timeout

Developers and agents

Agent API

Agent API endpoints let a SaaS backend or AI agent create invoices without using the browser dashboard. All Agent API requests require a server-side API key. Use Idempotency-Key when an agent may retry the same create request, so retries return the same invoice instead of creating duplicates.

Authorization: Bearer $FUNDLINE_API_KEY
x-api-key: $FUNDLINE_API_KEY

curl -X POST http://127.0.0.1:5190/api/agent/invoices \
  -H "Authorization: Bearer $FUNDLINE_API_KEY" \
  -H "Idempotency-Key: client-ltd-2026-06-retainer" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantWallet": "0xYourMerchantWallet",
    "merchantName": "Fundline Studio",
    "clientName": "Client Ltd",
    "clientEmail": "billing@client.com",
    "dueDate": "2026-06-30",
    "items": [
      { "description": "Consulting package", "quantity": 1, "unitPrice": 250 }
    ]
  }'

Get an API key

Open the dashboard, connect your wallet, and go to API keys to create a key. The secret is shown once at creation, so store it safely. A key is scoped to your wallet: invoices it creates are billed to your wallet, and workflow runs it starts are attributed to it.

Quick start for agents

An autonomous agent can discover and run any live workflow and pay from its own Arc wallet. No account or API key is required for workflow runs (a key is optional, only for higher rate limits or the Invoice API). The machine-readable guide is at GET /llms.txt.

1. Discover: GET /api/workflows lists every workflow with its slug and per-tier price; add ?q=keyword to search. GET /api/config returns chainId, usdcTokenAddress, runEscrowAddress, and which payment gates are enabled. Tiers are normal, plus, and pro (default normal); there is no standard tier.
2. Pick a payment method (all non-custodial, paid in USDC on Arc):
   • x402: one USDC transfer per run. Simplest; good for occasional runs.
   • Escrow: fund a per-run escrow; refund on failure is contract-guaranteed (trustless). Good when you want an on-chain refund guarantee.
   • Circle Gateway (gasless): pre-fund a Gateway balance once, then pay per run off-chain with no gas and sub-second settlement. Best for high-frequency, agent-to-agent use.
3. Run: send Accept: application/json to get one JSON response (steps, output, settlement tx) instead of the browser stream.

curl "https://fundline.xyz/api/workflows?q=research"
# -> { "workflows": [ { "slug": "client-research", "name": "Client Research",
#      "tiers": { "normal": { "units": "30000", "usdc": "0.03" } } } ],
#      "chainId": 5042002, "usdc": "0x3600...0000" }

Run a workflow from an agent

An agent can run any live workflow over HTTP. Runs are billed per run in USDC through a non-custodial per-run escrow: the agent funds its own run from its own Arc wallet, and the run is refunded automatically if it fails. Send Accept: application/json to receive one JSON response instead of the streaming response the browser uses.

1. Read GET /api/config for runEscrowAddress, usdcTokenAddress, chainId, and workflowPrices.
2. Call POST /api/workflows/:slug/quote to get a runId and the exact amount.
3. From your own Arc wallet, approve the escrow for the USDC amount, then call fund(runId, amount) on the run escrow.
4. Call POST /api/workflows/:slug/run with your API key and the runId to execute and settle.

curl -X POST http://127.0.0.1:5190/api/workflows/client-research/quote \
  -H "X-API-Key: $FUNDLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tier": "normal" }'
# -> { "runId": "0x...", "amount": "30000", "amountUsdc": "0.03",
#      "escrowAddress": "0x...", "usdc": "0x3600...0000", "chainId": 5042002 }

# after approve + fund(runId, amount) from your own wallet:
curl -X POST http://127.0.0.1:5190/api/workflows/client-research/run \
  -H "X-API-Key: $FUNDLINE_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "runId": "0xYourFundedRunId",
    "tier": "normal",
    "prompt": "Research Acme Labs for a partnership call"
  }'
# -> { "output": "...markdown report...", "steps": [...],
#      "priceUsdc": "0.030000", "releaseTx": "0x...", "runId": "0x...",
#      "explorerUrl": "https://testnet.arcscan.app/tx/0x..." }

Every run charges its fixed per-tier USDC price (see workflowPrices in the config), held and settled by the escrow. No owner or admin can withdraw a funded run: it can only release to the workflow provider on success or refund to the payer on failure.

Pay per call with x402

For lighter pay-per-call, an agent can use the x402 flow instead of the escrow. Call POST /api/workflows/:slug/run with no payment: you get an HTTP 402 with a quote. Pay by transferring the exact USDC price to the payTo treasury address, then retry the same request with an X-PAYMENT header (base64 JSON of your payer wallet and the transaction hash). The response is JSON, with an X-PAYMENT-RESPONSE header echoing the settled transaction. Each payment settles one run; a failed run is refunded to the payer.

# 1. Request with no payment -> HTTP 402 with a quote:
curl -X POST http://127.0.0.1:5190/api/workflows/client-research/run \
  -H "X-API-Key: $FUNDLINE_API_KEY" -H "Content-Type: application/json" \
  -d '{ "tier": "normal", "prompt": "Research Acme Labs" }'
# -> 402 { "accepts": [ { "scheme": "exact", "maxAmountRequired": "30000",
#      "asset": "0x3600...0000", "payTo": "0xTreasury", "network": "eip155:5042002" } ] }

# 2. Transfer 30000 (0.03 USDC) to payTo from your wallet, then retry with proof:
PAYMENT=$(printf '{"payerWallet":"0xYourWallet","txHash":"0xYourTransferTx"}' | base64)
curl -X POST http://127.0.0.1:5190/api/workflows/client-research/run \
  -H "X-API-Key: $FUNDLINE_API_KEY" -H "Accept: application/json" \
  -H "X-PAYMENT: $PAYMENT" -H "Content-Type: application/json" \
  -d '{ "tier": "normal", "prompt": "Research Acme Labs" }'
# -> 200 { "output": "...", "releaseTx": "0xYourTransferTx", ... }

Pay per call with Circle Gateway (gasless)

For high-frequency, agent-to-agent use, Fundline accepts Circle Gateway (Nanopayments). The agent pre-funds a Gateway balance once (a single on-chain deposit), then pays per run with an off-chain signed authorization that Circle verifies and settles in batches: no gas, sub-second per call. Non-custodial: the balance stays in the agent's own Gateway account, and only the exact run price settles to Fundline after a successful run. This gate is offered when workflowGatewayEnabled is true in GET /api/config.

Use Circle's @circle-fin/x402-batching client: create a client for arcTestnet with your wallet, deposit() once, then pay() the run URL. The client handles the 402 challenge, signs the authorization, and retries.

import { GatewayClient } from "@circle-fin/x402-batching/client";

const gateway = new GatewayClient({ chain: "arcTestnet", privateKey: process.env.AGENT_PRIVATE_KEY });

// One-time on-chain deposit into the Gateway balance:
await gateway.deposit("1");

// Then pay and run gasless, per call, from that balance:
const { data, amount } = await gateway.pay(
  "https://fundline.xyz/api/workflows/swot-analysis/run",
  { method: "POST", headers: { Accept: "application/json" },
    body: { tier: "normal", prompt: "SWOT for a USDC invoicing tool" } }
);
console.log("Paid", amount, "USDC:", data.output);

A runnable example is examples/gateway-agent-demo.js; the escrow and x402 agent demos are in examples/circle-agent-demo.js.

Run history

Every run response already returns priceUsdc, the settlement releaseTx, and an explorerUrl (Arcscan link) so an agent can verify each run on chain. To list past runs, an agent identifies itself by wallet: it signs the standard Fundline sign-in message with the same wallet it paid from, then calls GET /api/workflows/runs with the wallet, signature, and issued-at headers. The response holds the runs recorded under that wallet. All of this is also public on chain under the agent wallet, so Arcscan is the ultimate source of truth.

curl https://fundline.xyz/api/workflows/runs \
  -H "x-fundline-wallet: 0xYourWallet" \
  -H "x-fundline-signature: 0xYourSignature" \
  -H "x-fundline-issued-at: 2026-07-04T00:00:00.000Z"
# -> { "wallet": "0xYourWallet", "count": 2, "runs": [
#      { "at": "...", "slug": "client-research", "tier": "normal",
#        "priceUsdc": "0.030000", "mode": "x402", "settlementTx": "0x...",
#        "explorerUrl": "https://testnet.arcscan.app/tx/0x..." } ] }

Remote MCP server

Fundline also speaks the Model Context Protocol at POST /mcp, so an MCP client (Claude, Cursor, and autonomous agents like Hermes Agent or OpenClaw) can connect by URL and use Fundline workflows as tools. A Fundline API key is optional for workflow runs and raises the available rate limit. Tools: list_workflows, run_workflow, get_run, and list_runs.

{
  "fundline": {
    "url": "https://fundline.xyz/mcp",
    "headers": { "Authorization": "Bearer $FUNDLINE_API_KEY" }
  }
}

Durable asynchronous run

Treat quote, payment, enqueue, and polling as one logical run. Save the jobId, runId, and recoveryToken before sending USDC. The recovery token authorizes result access, so do not log, commit, or share it.

1. Call list_workflows and select a valid slug and tier.
2. Call run_workflow without payment and set paymentMode to escrow.
3. Verify chain ID 5042002, canonical USDC, escrow address, and the exact quoted amount.
4. Approve only that amount and call fund(runId, amount) from the payer wallet.
5. Call run_workflow with payment.jobId, payment.runId, and payment.recoveryToken.
6. Poll get_run, honoring retryAfterSeconds, until succeeded, refunded, or failed.

# 1. Quote. POST each JSON-RPC request to https://fundline.xyz/mcp
{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_workflow","arguments":{"slug":"proposal-doc","tier":"normal","prompt":"Create a concise proposal","paymentMode":"escrow"}}}
# -> { "status":"awaiting_payment", "jobId":"0x...", "runId":"0x...",
#      "recoveryToken":"keep-private", "amount":"10000", "chainId":5042002, ... }

# 2. After approve + fund(runId, amount), enqueue the same job.
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"run_workflow","arguments":{"slug":"proposal-doc","tier":"normal","prompt":"Create a concise proposal","payment":{"jobId":"0x...","runId":"0x...","recoveryToken":"keep-private"}}}}
# -> { "status":"queued", "jobId":"0x...", "retryAfterSeconds":1 }

# 3. Poll without paying again.
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_run","arguments":{"jobId":"0x...","recoveryToken":"keep-private"}}}
# -> processing | settling | succeeded | refunding | refunded | failed

If the MCP connection times out, call get_run again with the same credentials. Do not create or fund another job. Successful results remain retrievable for seven days by default.

Legacy direct x402: older clients may obtain an HTTP 402 challenge from the workflow /run endpoint, pay it, then call MCP run_workflow with only payment.payerWallet and payment.txHash. New MCP clients that need x402 should request paymentMode: "x402" so they receive durable job credentials before paying. Escrow remains recommended because refunds are contract-backed. Some clients reach remote MCP servers through a local bridge such as mcp-remote.

RPC fallback for agent wallets

Verify every RPC returns Arc Testnet chain ID 5042002 (0x4cef52) before signing. Use canonical USDC at 0x3600000000000000000000000000000000000000 with six decimals. Try RPCs in this order:

1. https://rpc.drpc.testnet.arc.network
2. https://rpc.blockdaemon.testnet.arc.network
3. https://rpc.quicknode.testnet.arc.network
4. https://rpc.testnet.arc.network

Rotate only after a connection timeout, HTTP 429, HTTP 5xx, or JSON-RPC -32011. Do not rotate and blindly retry a contract revert, insufficient funds, invalid input, bad signature, or wrong chain response.

const ARC_RPCS = [
  "https://rpc.drpc.testnet.arc.network",
  "https://rpc.blockdaemon.testnet.arc.network",
  "https://rpc.quicknode.testnet.arc.network",
  "https://rpc.testnet.arc.network",
];

async function arcRpc(method, params = []) {
  let lastError;
  for (const url of ARC_RPCS) {
    let response;
    try {
      response = await fetch(url, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
      });
    } catch (error) {
      lastError = error;
      continue;
    }
    if (response.status === 429 || response.status >= 500) {
      lastError = new Error("RPC temporarily unavailable");
      continue;
    }
    const body = await response.json();
    if (body.error?.code === -32011) {
      lastError = new Error(body.error.message);
      continue;
    }
    if (body.error) throw new Error(body.error.message);
    return body.result;
  }
  throw lastError || new Error("All Arc RPC endpoints are unavailable");
}

For eth_sendRawTransaction, sign once and retain the transaction hash. After an ambiguous timeout, query eth_getTransactionByHash and eth_getTransactionReceipt through another RPC before rebroadcasting the same signed raw transaction. Never create a second payment with a new nonce just because one RPC lost its response.

Webhooks

Payment events for external systems

Webhooks notify your backend when an invoice becomes paid. A webhook can be signed with X-Fundline-Signature using HMAC SHA-256.

curl -X POST http://127.0.0.1:5190/api/agent/webhooks \
  -H "Authorization: Bearer $FUNDLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantWallet": "0xYourMerchantWallet",
    "url": "https://example.com/webhooks/fundline",
    "event": "invoice.paid",
    "secret": "optional_shared_secret"
  }'

{
  "event": "invoice.paid",
  "sentAt": "2026-06-11T00:00:00.000Z",
  "invoice": {
    "id": "37f1cdd4727c0d85d32b",
    "number": "INV-2026-0001",
    "status": "paid",
    "total": 250,
    "merchantWallet": "0x...",
    "payerWallet": "0x...",
    "txHash": "0x...",
    "paymentLink": "http://127.0.0.1:5190/pay/37f1cdd4727c0d85d32b"
  }
}

Delivery audit

Webhook logs

Each webhook delivery attempt is stored on the server with delivery ID, invoice ID, target URL, success state, HTTP status, error preview and duration. Secrets are never returned in log responses.

curl "http://127.0.0.1:5190/api/agent/webhook-logs?merchantWallet=0xYourMerchantWallet&limit=20" \
  -H "Authorization: Bearer $FUNDLINE_API_KEY"

Reference

Network

Contracts

Settlement contracts

Every settlement contract is non-custodial: it only moves USDC with transferFrom(payer, recipient) and emits events. It holds no balance and has no owner, admin, or withdraw path. Source is verified on Arcscan.

The original PaymentRouter (0x7f3bCf33711F981e2d67870D5Cdb5503f01e1a24) is superseded by FundlineMemoRouter, which keeps the same payInvoice entry point and the same InvoicePaid event, so existing integrations keep working.

Configuration

Server environment

All secrets stay on the server. Do not expose private keys, Telegram bot token or API key in browser code.

Security

Security baseline

• The settlement routers are non-custodial and do not hold USDC.
• A batch payout is atomic: it pays everyone or reverts, never half a payroll.
• The payer approves only the amount required by the payment page.
• Paid status is set only after the server confirms a matching on-chain payment.
• A single transaction can never settle two invoices.
• Telegram bot token, API key and deployer private key stay in server-side environment files.
• Webhook signatures should be verified by production receivers before trusting payloads.

FAQ

Common questions