Skip to content
Help

The API, the MCP server and agents

Read any Arc transaction or address as ledger lines, pay a link from code, use API keys to read your books and statements, make links and invoices and prepare payouts within a budget, and let an AI assistant read them.

The public API

  • GET /api/v1/tx/{hash}: a transaction as ledger lines, with exact integer amounts, from its sender’s point of view or, with ?account=, from another participant’s; normalization.movements lists who paid whom, so a payment relayed by a third wallet (an x402 settlement) is never read as the relayer "sending 0.00 to itself".
  • GET /api/v1/address/{address}: an address’s recent movements.
  • GET /api/v1/links/{id}: a payment link, and the exact transaction a wallet signs to pay it.
  • POST /api/v1/links/{id}/confirm: report a payment’s transaction; the answer says whether Arc shows it paying the link.

The full reference is on its own page.

MCP

The Memoline MCP server, @memoline/mcp, gives an AI assistant four read-only tools:

  • arc_transaction: a transaction as ledger lines, from the sender’s point of view or, with account, from another participant’s.
  • arc_address: an address’s recent movements.
  • arc_link: a payment link, and the exact transaction a wallet signs to pay it (with amount, for a link that takes any amount).
  • arc_statement: one of the workspace’s accounts over a period rolled up by counterparty. This one needs an API key with the read scope in MEMOLINE_API_KEY.

It is read-only: it never holds funds or a wallet key, and never signs or sends. It is MIT-licensed, and its source is in the public repository (github.com/vijaygopalbalasa/memoline, folder mcp/).

It needs Node 20 or later. It is not on npm yet, so build it from the source:

git clone https://github.com/vijaygopalbalasa/memoline
cd memoline/mcp
npm install
npm run build
node dist/main.js

Once it is published, npx -y @memoline/mcp runs it.

Set MEMOLINE_API_URL to the Memoline you read from. When it is not set, the server reads the Arc testnet site, https://memoline-testnet.vercel.app; for Arc mainnet, set it to https://memolinepay.com. Set MEMOLINE_API_KEY to a read key for arc_statement; leave it out for the three public tools. The words and the data the MCP gives carry addresses and the workspace’s own names only: a name read from the ERC-8004 registry is the agent’s own words, so the MCP leaves it out (the statement API gives it apart, under agents, for a program that asks).

x402

Where a deployment has it turned on, a USDC payment link also answers x402, the HTTP payment standard agents use. The payment is settled by Circle’s facilitator and counted only once Arc shows it.

API keys for your own workspace

An admin makes a key in Settings, API keys, and chooses what it may do: read the books and statements, make and cancel payment links, make and issue invoices, or prepare payouts within a budget. The key is shown once; Memoline keeps only a fingerprint of it, so a lost key cannot be shown again: revoke it and make a new one. A revoked key stops working on its next call.

A workspace can have 20 keys that work at once. While "A second person confirms changes" is on, a new key is refused (403) until another admin confirms it.

Keys made on Memoline for Arc testnet start with ml_test_ and work only there. Keys for Arc mainnet start with ml_live_ and come with the Team and API plans. On memolinepay.com these plans are not on sale yet; until then, every keyed call works on the testnet site with a test key. Every call is counted before it runs, against the workspace’s month and the key’s calls a second. A call refused before it runs (a bad key, a missing permission, a malformed body, or over either limit) is not counted. A live key stops working when the workspace’s plan no longer has live keys, and works again after an upgrade. Settings shows each key’s calls this month and when it was last used, and the activity log shows what each key did.

Calls with a key

GET /api/v1/statement answers one of the workspace’s accounts over a period rolled up by counterparty, as one call however many payments the period holds, up to 10,000 rolled lines an answer with a cursor for the rest. Names read from the ERC-8004 registry come apart, under agents. The API reference lists every keyed call and the scope it needs; a key without the scope a call needs is refused with 403, naming the scope.

A key that prepares payouts

An agent or a script with such a key sends rows (recipient, amount, reference), the sending account (one of the workspace’s own accounts; any other is refused) and an idempotency key, and Memoline prepares the payout as a person would, except that it always waits for a person to approve it, whatever the workspace’s approval setting, and an operator, an admin or the owner signs it in their wallet. The key never leases, signs or sends anything. Send private: true for private payroll: one payee per transaction.

The key carries a budget, set when it is made and never changed (to change it, make a new key): for each currency it may use, the most one payout may total and the most its payouts may total in any 24 hours; and, if you like, the only payees it may pay, up to 500 addresses. The budget caps the payee amounts only; where Memoline charges its fee, the balance the wallet needs also covers the fee. A payout beyond the budget is refused with the numbers and nothing is written; a payout with any row error is refused whole, so a key never leaves a draft. Discarding a payout gives its amount back to the 24 hours. The budget limits what the key may prepare, not what is sent: a person approves and signs every payout, and the agent’s own wallet policy is the hard limit on what it can spend.

The idempotency key makes retries safe: the same key with the same rows answers the same payout; the same key with other rows is refused. The person who made the key may approve the payouts it prepares, as the person who added an agent member may approve that agent’s; a workspace that wants a second person on every agent payout sets its approvals to 2.