Integrating with FinMesh

1. 1. Get credentials. The operator registers your application in the FinMesh admin and hands you a client_id and a secret. There is no self-service signup: this is one person’s financial data, and access is granted by them, deliberately, per consumer.

2. 2. Mint a link_token. The response includes a hosted link_url for the operator to open.

   POST /v1/link/token/createcopy

   curl -X POST https://finmesh.yan.codes/v1/link/token/create \
     -H 'Content-Type: application/json' \
     -d '{
       "client_id": "$CLIENT_ID",
       "secret": "$SECRET",
       "redirect_uri": "https://your.app/finmesh/callback"
     }'

3. 3. The operator picks accounts. They open link_url, tick the accounts your application may read, and land back on your redirect_uri with ?public_token=…. Omit redirect_uri and the hosted page prints the token for them to hand over instead.

4. 4. Exchange it. Once, for an access_token that does not expire — store it like a password.

   POST /v1/item/public_token/exchangecopy

   curl -X POST https://finmesh.yan.codes/v1/item/public_token/exchange \
     -H 'Content-Type: application/json' \
     -d '{
       "client_id": "$CLIENT_ID",
       "secret": "$SECRET",
       "public_token": "$PUBLIC_TOKEN"
     }'
   
   # → { "access_token": "…", "item_id": "…", "request_id": "req_…" }

5. 5. Sync. No cursor means “from the beginning” — the initial full history.

   POST /v1/transactions/synccopy

   curl -X POST https://finmesh.yan.codes/v1/transactions/sync \
     -H 'Content-Type: application/json' \
     -d '{
       "client_id": "$CLIENT_ID",
       "secret": "$SECRET",
       "access_token": "$ACCESS_TOKEN",
       "count": 500
     }'

• Everything is POST with a JSON body. Including the reads. A GET returns 405 with Allow: POST.
• Credentials travel in the body, not in headers. client_id and secret authenticate the request; access_token scopes it to one item. There is no Authorization header on the consumer plane.
• Every response carries a request_id. Quote it when reporting a problem — it is in the server log too. (The bare 405 for a wrong verb is the one exception; it never reached a handler.)
• No CORS headers are sent, on purpose. Call /v1 from your server. A secret that has been in a browser is a leaked secret.
• Money is a JSON number in the account’s native currency, with iso_currency_code alongside it. Native is authoritative; amount_usd is a convenience.

An item is a grant: “this consumer may read these accounts.” The accounts already exist — the operator registered them and has been feeding them CSVs and screenshots, usually for a while — so Link is a picker over real accounts rather than a credential capture. One consequence worth knowing: a grant can span institutions, so institution_id on an item is the single institution when there is one and null when there are several. The full set is always in institutions.

The operator can also skip the browser entirely and mint an item and its access_token straight from the admin, then hand you the token. That is the same object by a shorter path — if you were given an access_token directly, start at syncing.

GET /v1/link/:link_token is the one exception to POST-only: it is the hosted page the operator opens in a browser, not an API call.

cursor is an opaque watermark over an append-only mutation log. Omit it for the initial full sync, then persist next_cursor after each page you have committed — not when you receive it. Replaying a cursor returns the same page, so a crash mid-page costs you a repeat, never a gap.

let cursor = await store.readCursor();   // null on first run

for (;;) {
  const page = await post("/v1/transactions/sync", { cursor, count: 500 });

  await store.transaction(async (tx) => {
    for (const t of page.added)    await tx.upsert(t);
    for (const t of page.modified) await tx.upsert(t);
    for (const t of page.removed)  await tx.delete(t.transaction_id);
    await tx.writeCursor(page.next_cursor);   // same commit as the rows
  });

  cursor = page.next_cursor;
  if (!page.has_more) break;
}

• Upsert, don’t insert. A transaction can appear in added and later in modified. Within a single page only the last mutation for a transaction is reported, so a row added and removed inside one window arrives as a removal only.
• removed means “no longer yours to show”, which covers a transaction the operator deleted and an account whose grant was revoked. It is not a statement that the money never moved.
• Only approved rows are ever visible. Every source — CSV, screenshot, manual, chain, broker — commits immediately, so a row appears on the next sync after it was collected. The exception is an asset the operator has not yet tracked: its rows stay held until they do, and then arrive asadded.
• A new item backfills. Granting an account writes added for its whole history, so your first sync returns years of data even though the item is seconds old.
• count defaults to 100 and is capped at 500. Out-of-range values are clamped, not rejected.

Event types

Every event body carries event_id, webhook_type, webhook_code, type, item_id, account_id, created_at, plus the payload fields above merged in at the top level.

Verifying a webhook

Sign over the raw body — re-serializing parsed JSON will not match. The signing secret is shown in the admin next to the webhook URL.

import crypto from "node:crypto";

const TOLERANCE_S = 300;

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => kv.split("=")),
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;

  // Bound replay: the timestamp is inside the signed string, so an attacker
  // cannot re-date a captured delivery without invalidating it.
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_S) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1 ?? ""),
  );
}

Draining the relay

let cursor = await store.readEventCursor();

const page = await post("/v1/events/poll", { cursor, count: 100 });
for (const event of page.events) await handle(event);

// Ack only what you have handled: everything up to this cursor is dropped
// from the queue, and the queue is the only copy in relay mode.
await post("/v1/events/ack", { cursor: page.next_cursor });
await store.writeEventCursor(page.next_cursor);

{
  "error_type": "INVALID_INPUT",
  "error_code": "INVALID_ACCESS_TOKEN",
  "error_message": "The access_token is invalid, revoked, or belongs to another consumer.",
  "display_message": null,
  "request_id": "req_9f2c1a4b7e0d3c58"
}

Authentication failures are deliberately indistinguishable: a wrong client_id and a wrong secret return the same message, and both are compared in constant time.

Verbatim is the point: a client that already renders Plaid categories needs no mapping layer. Mapping PFC onto your own chart of accounts is your job, not FinMesh’s — the taxonomy here will never grow a FinMesh-specific category. Fetch the full list from /v1/categories/get; the primaries are:

confidence_level reflects how the classification was made — a learned rule table handles the common descriptions and a model handles the tail. Classification is also opt-in on this instance, so personal_finance_category being null is normal and means “not classified”, never “uncategorized spending”.

This instance serves one person’s financial data and is usually reachable only over their private network. If a call is timing out rather than failing, the likeliest answer is that you are off that network.