Skip to content

Developers

The API reference

Read any Arc mainnet transaction or address as ledger lines: each USDC movement counted once (Arc logs an ERC-20 USDC payment twice), gas split across the lines that paid it, and the reference from its Arc Memo attached. The same reading Memoline’s own books use. Free, no key, JSON. With a key, your own workspace's books and statements, links and invoices too, and payouts prepared within a budget for a person to approve and sign.

Every call below goes to https://memolinepay.com.

Make a key

An admin or the owner of a workspace makes keys.

A transaction

GET /api/v1/tx/{hash}

Try it on the first payout made with Memoline: /api/v1/tx/0x6459e57b…

The first payout on Arc mainnet, shortened:

{
  "apiVersion": 1,
  "network": "arc-mainnet",
  "chainId": 5042,
  "transaction": {
    "hash": "0x6459…3eaf", "from": "0x427c…1458", "status": "success",
    "blockNumber": "22321291", "blockTime": 1790153300,
    "fee": "0.0043416804", "feeNative18": "4341680400000000"
  },
  "lines": [
    {
      "direction": "out", "token": "USDC",
      "amount": "1.00", "amount6": "1000000", "amountNative18": "1000000000000000000",
      "counterparty": "0xe4Bb…e175", "reference": "INV-2026-001",
      "fee": "0.0014472268", "feeNative18": "1447226800000000", …
    },
    …
  ],
  "normalization": { "gasPayer": "0x427c…1458", "movements": [ { "from": "0x427c…1458", "to": "0xe4Bb…e175", "amount": "1.00", "kind": "transfer", … }, … ], … }
}

Lines are from the sender’s point of view. Add ?account=0x… for another participant’s: a transfer sent by a third wallet (an x402 settlement relayed by Circle’s facilitator) moves nothing for its sender, so the payee’s lines, or normalization.movements, are what say who paid whom. An account that took no part gets no lines and a sentence saying so.

An address

GET /api/v1/address/{address}

The address’s movements in every stablecoin Memoline reads, over about the last day. coverage says which blocks were read; when complete is false, the oldest lines may be missing. For longer histories, sign in and import the address into a ledger.

One-time announcements

GET /api/v1/announcements?after={block}.{log}

Arc testnet only today: on any other network this route answers 404 with “One-time addresses are not available on this network yet.” The ERC-5564 announcements Memoline keeps: every announcement of a payout made through Memoline, and every other one made on Arc testnet since Memoline began reading it, oldest first, 2,000 at a time. Public, no key. Each item is one announcement: its block and log position, the transaction, the one-time address (stealthAddress), the ephemeral public key, the view tag and the ERC-5564 metadata. It is never filtered by payee: a payee’s browser reads them all and keeps only its own, so reading them tells Memoline nothing about which are whose. A payout made through Memoline still pairs each payment’s one-time address with its payee: its rows carry both. Pass the next of one answer as after for the rest; readTo is how far Arc has been read.

{
  "items": [
    {
      "block": "59604684", "log": 3, "tx": "0x…",
      "stealthAddress": "0x…", "ephemeralPublicKey": "0x…",
      "viewTag": 42, "metadata": "0x…"
    }
  ],
  "next": "59604684.3", "readTo": "59604812"
}

It allows 120 reads an hour from each connection (by IP), counted in hourly windows, and answers 429 with retry-after: 3600 past that.

x402

GET or POST /api/v1/links/{id}/x402   (PAYMENT-SIGNATURE: <base64 payment>)

Where a deployment has it turned on, a USDC link also answers x402 version 2: without a payment it answers 402 with PAYMENT-REQUIRED (the exact scheme on eip155:5042, USDC); with a signed authorization it has Circle’s facilitator settle it, then counts it only once Arc shows the transfer. If Arc does not show it within about fifteen seconds the answer is 202 with the settlement in PAYMENT-RESPONSE; it is recorded by the next scan, and until then a fixed link answers 409 rather than ask to be paid again. Where x402 is off, the address answers 501 and the call above works for any agent.

Status

GET /api/v1/status

The same checks as the status page, as JSON, and 503 while any check is down, so an uptime monitor notices. No key; cached for 30 seconds.

Webhooks

A workspace can have Memoline tell its server what happens in it: payment.received for each payment, link.settled when a link is paid in full, refund.sent for a refund, run.completed when a payout finishes, import.completed when an import finishes, run.approval_requested when a payout waits for approval, run.approved once, when its approvals become enough, run.rejected when it is rejected, with the reason, invoice.overdue when an invoice becomes overdue, run.cycle_ready when a schedule has made a payout that is ready to check and sign, and schedule.paused when a schedule pauses itself, with the reason. Each request carries Memoline-Signature: t=…,v1=…, an HMAC-SHA256 of t + "." + body with the endpoint’s secret, and Memoline-Delivery, the same on every retry of one event. A failed delivery is tried again with growing waits, up to 12 tries: when a new event comes in, when an admin or the owner opens the Webhooks page or presses Retry now, and at least once a day. Answer 2xx to accept; treat a repeated delivery id as already handled.

Two of these carry a schedule’s own data and no payees. The run.cycle_ready data is run: { id, name, day, rows, total, token, approval } and words: the payout’s id, the schedule’s name, the day it pays, how many payments and their total, the currency, whether it needs approval before it is signed, and a sentence that names the schedule, the day and the total. The schedule.paused data is schedule: { id, name, why }: its id, its name, and why it paused, in words.

A payment.received payment carries payerScreen: the wallet that paid against the US Treasury’s sanctions list (OFAC), the UK Sanctions List and the EU’s financial sanctions list when the payment was recorded, listed, clear or not-read: listed when any of them names it, clear when all three were read in the last 7 days and none names it, not-read when one was not. Beside it, payerLists names the lists that named a listed wallet: ofac, uk, eu, empty otherwise. The payment is recorded whatever they say; they are fields, never an event of their own, and a later answer for a not-read payment is not sent again.

Line fields

direction
"out", "in" or "self", from the point of view of the address read (for a transaction, its sender).
account
On /ledger only: which of the workspace’s accounts the line belongs to.
token
"USDC" or "EURC".
amount
The amount as a decimal, for display.
amount6
The exact amount in the token’s 6-decimal units, as an integer string.
amountNative18
For USDC, the exact native amount in 18-decimal units; null for EURC.
counterparty
The other address.
party
Who the line is with: the counterparty, except for a payment to a one-time address, where it is the payee whose keys made the address. Join lines on it.
reference
The reference from the Arc Memo attached to the payment, or null; on /ledger, for a payment to a one-time address, the payout’s reference kept in the books (it is not on Arc).
memoId
The memo’s ID, or null.
fee, feeNative18
This line’s share of the gas, in USDC; zero when the address did not send the transaction.
txHash, logIndex, blockNumber, blockTime
Where the movement is on the chain. blockTime is in seconds, UTC, or null when its time could not be read.
note
Anything the line needs to say, for example that its gas could not be read.

Amounts are integers written as strings, because JSON numbers lose precision past 2^53. Never parse them as floating point.

How the lines are counted

  • USDC is counted from the system Transfer log (18 decimals), not the duplicate the USDC contract also logs, except for a USDC transfer to oneself, which only the contract logs.
  • Gas belongs to the transaction’s sender. It is split evenly across the lines of a transaction, with the remainder on the first, so the lines add up to the exact fee.
  • EURC is counted from the EURC contract’s own log. Its gas is USDC.

For agents

The Memoline MCP server, @memoline/mcp (MIT licence), offers the same reads to an AI agent as four read-only tools: arc_transaction (a hash, and optionally the account whose point of view to take), arc_address (an address), arc_link (a link id, and an amount for a link that takes any amount) and arc_statement (an account, a stablecoin such as USDC or EURC, and from and to in seconds since 1970), which reads your workspace's own books rolled up by counterparty with a read key in MEMOLINE_API_KEY. It holds no keys of its own and never signs or sends anything. It reads Arc testnet unless MEMOLINE_API_URL names another Memoline; for this site, set it to https://memolinepay.com.

It is not on npm yet: build it from its source, the mcp folder of github.com/vijaygopalbalasa/memoline, with Node 20 or later, then have your MCP client start node dist/main.js in that folder. Once it is published, npx -y @memoline/mcp runs it without the source.

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

An agent with its own wallet can also join a workspace in the agent role. It prepares payouts; a person approves each one, and an operator, an admin or the owner signs it.

Your own workspace, with a key

An admin or the owner makes a key in Settings, API keys, and chooses what it may do: read the books, make and cancel payment links, make and issue invoices, or prepare payouts within a budget. The key is shown once. Send it in the Authorization header; keyed calls never use a browser's sign-in, so keep the key on your server.

On Arc mainnet, keys come with the Team and API plans, which are not on sale yet. Until then, every keyed call works on the testnet site with a test key.

GET    /api/v1/ledger?account=&token=&from=&to=&limit=&before=
GET    /api/v1/links

POST   /api/v1/links
{
  "token": "USDC",
  "amount": "12.50",
  "reference": "ORDER-7"
}

POST   /api/v1/links/{id}/cancel
GET    /api/v1/invoices

POST   /api/v1/invoices
{
  "customer": { "name": "Rossi" },
  "currency": "USDC",
  "lines": [{
    "description": "Work",
    "quantity": "2",
    "unitPrice": "10"
  }],
  "issue": true
}

GET    /api/v1/usage

POST   /api/v1/payouts
{
  "token": "USDC",
  "sender": "0x…",
  "idempotencyKey": "order-7",
  "rows": [{
    "recipient": "0x…",
    "amount": "12.50",
    "reference": "INV-7"
  }]
}

GET    /api/v1/payouts/{id}
DELETE /api/v1/payouts/{id}
GET    /api/v1/payouts/budget
GET    /api/v1/statement?account=&token=&from=&to=[&after=]
GET    /api/v1/schedules
GET    /api/v1/upcoming

Authorization: Bearer ml_test_...

Each call needs a scope. A key without the scope a call needs is refused with 403, naming the scope.

GET /api/v1/ledger
read
GET /api/v1/links
read
POST /api/v1/links
links:write
POST /api/v1/links/{id}/cancel
links:write
GET /api/v1/invoices
read
POST /api/v1/invoices
invoices:write
GET /api/v1/statement
read
POST /api/v1/payouts
payouts:prepare
GET /api/v1/payouts/{id}
read or payouts:prepare
DELETE /api/v1/payouts/{id}
payouts:prepare
GET /api/v1/payouts/budget
payouts:prepare
GET /api/v1/usage
any key
GET /api/v1/schedules
read
GET /api/v1/upcoming
read

/statement answers one of the workspace's accounts over a period rolled up by counterparty: the totals, the balances Arc reports at the period's edges and whether it closes, and one line per counterparty and direction with the count of payments, exact and never netted. It is computed in the database and counted as one call however many payments the period holds; at most 10,000 rolled lines an answer, with next as after for the rest. Line by line stays on /ledger. Names are the workspace's own; names read from the ERC-8004 registry come apart, under agents, with their source. An account with no books in the workspace answers 404.

The schedules call lists the workspace’s recurring payouts, read only: each carries its name, paying wallet, currency, how often it repeats and until when, its next and last payout, who prepares it, and how many payments it makes with their total, never the payees. A person saves and changes a schedule in the app, never a key.

A key with payouts:prepare prepares a payout for a person to approve and an operator, an admin or the owner to sign in their wallet; the key never leases, signs or sends anything. Send rows, or csvText with the same three columns, not both. Such a key carries a budget per currency (the most one payout may total, and the most its payouts may total in any 24 hours) and may carry a payee list; a payout beyond them is refused with the numbers, and nothing is written. A currency the key has no budget for is refused with 403. Every payout a key prepares needs at least one approval, whatever the workspace's approval setting. The sender must be one of the workspace's own accounts (403 otherwise). idempotencyKey is required: a new payout answers 201 with created true, the payout and any warnings; a repeat with the same key and rows answers the same payout with 200 and created false; the same key with other rows is refused (409). Rows with any error refuse the whole payout (400). The budget limits what the key may prepare, not what is sent; the agent's own wallet policy is the hard limit on what it can spend.

Send "private": true for “Private payroll: one payee per transaction”. A payee who opens their transaction sees only their own payment. Anyone who looks up the paying address still sees every payment, the amounts and the payees. You sign one transaction per payee, and each pays its own network fee. The payout, as POST answers it and GET /api/v1/payouts/{id} reads it, carries private (true or false) and fee: Memoline’s fee for the payout as decided when it was made, { to, total, total6, payees, free } (the address it is paid to, the total as a decimal and in 6-decimal units, how many payments it covers (one per row, rows set aside left out) and how many of them are free), or null when the payout was made without a fee. Each row carries its own fee and fee6, zero for a free row and null without a fee. This fee is not gas: it is paid in USDC, in the same transaction as the payments.

Send "oneTime": true for one-time addresses: each payment goes to a fresh one-time address made from the payee’s registered keys, announced in the same transaction, so the chain shows a payment to an address never seen before, not to the payee’s wallet. USDC only. The payout, as POST answers it and GET /api/v1/payouts/{id} reads it, carries oneTime (true or false), and each row carries oneTimeAddress, the one-time address the payment goes to once the payout is checked on Arc; null before that, for a payment set aside before one was made, and for a plain payment. Where the one-time contracts are not on the network, the payout is refused: “One-time addresses are not available on this network yet.”

Keys made on Memoline for Arc testnet start with ml_test_ and work only there; keys made for Arc mainnet start with ml_live_ and come with the Team and API plans. A workspace can have 20 keys that work. A key made while A second person confirms changes is on answers 403 until an admin or the owner other than the one who made it confirms it. A key’s budget and payee list (up to 500 addresses) are fixed when the key is made; to change them, make a new key. The ledger answers newest first, up to 1,000 lines; pass its next as before for the next page. A link made this way always pays the workspace owner's wallet.

Every call is counted before it runs. Free and Pro allow 2,000 calls a month for the workspace and 5 a second per key; Team allows 50,000 a month and 20 a second; API Starter, API Growth and API Scale allow 50,000, 500,000 and 3,000,000 a month and 10, 30 and 100 a second. A call over either answers 429. A call refused before it runs (bad key, missing scope, malformed body, over a limit) is not counted, and a live key stops, with 402, when the plan no longer has live keys. /usage says where you are. What a key does is in the workspace's activity log under the key's name.

Limits

Each connection (by IP) can make 300 transaction reads and 10 new address reads an hour. A mined transaction is kept once read and served again without counting. An address read is kept for five minutes, and repeats of it count against a separate allowance of 120 an hour. Claims are limited to 30 an hour and x402 payments to 60 an hour from each connection (by IP). Every endpoint answers any origin (CORS) and sets no cookies. Errors come back as { "error": "…" } with a sentence saying what went wrong.

Building on Arc and need higher limits, or help getting USDC accounting right in your own product? Write to hello@memolinepay.com, or see how Memoline calls Arc’s contracts. Terms: terms and privacy.