Transactions

Query confirmed and pending deposits and withdrawals, and annotate them for review.

List transactions

Returns newest-first. On Bitcoin and Dogecoin, each item also carries the full inputs and outputs arrays (every source and destination address with its amount) when the upstream provider supplies them.

XRP transactions carry destinationTag: for a deposit, the tag the payment was sent with; for a withdrawal, the tag it was sent to. It is null when there was none, and on every other chain.

TON transactions carry memo, the text comment: for a deposit, the comment the payment was sent with; for a withdrawal, the one it was sent with. It is null when there was none, when the payload was not a readable text comment (binary or encrypted comments are recorded this way), and on every other chain.

Every transaction carries wallet, the id and name of the wallet it was recorded against: the one holding the address it touched. Filter by walletId to list only that wallet's transactions.

curl "https://api.guveno.com/v1/transactions?walletId=12&direction=incoming&limit=50" \
  -H "Authorization: Bearer gv_live_your_key_here"

{
  "items": [
    {
      "id": 9001,
      "chain": "ethereum",
      "network": "mainnet",
      "direction": "incoming",
      "status": "confirmed",
      "txHash": "0xabc...",
      "confirmationCount": 14,
      "wallet": { "id": 12, "name": "Treasury ETH" },
      "assetMovements": [
        {
          "id": 31,
          "eventType": "native",
          "fromAddress": "0xSender...",
          "toAddress": "0xYourAddress...",
          "amount": "1.5",
          "asset": { "id": 3, "symbol": "ETH", "decimals": 18 }
        }
      ],
      "createdAt": "2026-06-14T11:52:10.000Z"
    }
  ],
  "pageInfo": { "nextCursor": "eyJpZCI6OTAwMX0", "hasNextPage": true }
}

Filtering

All filters are optional and combine (AND):

• walletId, addressId: scope to one wallet or address.
• chain, network: e.g. ethereum / mainnet.
• direction: incoming or outgoing.
• status: pending, confirmed or rejected.
• asset: asset symbol (e.g. ETH, BTC); matches any movement. TON still finds the TON network's coin, now GRAM.
• search: substring match against the tx hash or any from/to address.
• from, to: ISO-8601 date-time bounds on when the tx was first recorded.
• amountMin, amountMax: decimal amount bounds; matches any movement.
• marked: restrict to a review list — saved, flagged, flagged_open, flagged_resolved or assigned (see Review marks).

curl "https://api.guveno.com/v1/transactions?chain=bitcoin&status=confirmed\
&from=2026-06-01T00:00:00Z&to=2026-06-30T23:59:59Z\
&amountMin=0.01&search=bc1q" \
  -H "Authorization: Bearer gv_live_your_key_here"

Pagination

Pass the returned pageInfo.nextCursor back as cursor to fetch the next page. A null cursor means you've reached the end.

Get one transaction

Returns a single transaction in the same shape as a list item. Useful for following a link to a transaction someone flagged, without paging the whole feed.

curl "https://api.guveno.com/v1/transactions/9001" \
  -H "Authorization: Bearer gv_live_your_key_here"

Review marks

Every transaction carries a marks object — the review layer your team uses in the dashboard. There are two marks, and they differ in who can see them:

• ★ saved and its note — personal unless you share them. Your own "review later" queue. Nobody else's ★ is ever reported to you, and yours is never reported to them, until you set noteShared, which shows your ★ and its note to everyone who can already see the transaction, with your name.
• ⚑ flagged and the assignee — shared, with the author attached. A flag says "this needs attention", so everyone who can already see the transaction sees who raised it and why. A raised flag's note is always shared.

saved, noteShared, flagged and note at the top level are yours; shared lists every member's flag, and every ★ and note its author chose to share, with its author. Marks are organizational only — they never affect crediting, confirmations or balances.

A flag has a lifecycle, which is what makes the flagged list a queue rather than a pile. It is raised, then either resolved (reviewed and closed — resolvedAt and resolvedBy) or withdrawn (flagged: false, as if it had never been raised). It may also name one member it is waiting on (assignedTo), who is notified once. flagCount counts every flag; openFlagCount counts the ones still waiting on a review.

{
  "saved": true,
  "noteShared": false,
  "flagged": false,
  "flaggedAt": null,
  "note": null,
  "noteUpdatedAt": null,
  "resolvedAt": null,
  "resolvedBy": null,
  "assignedTo": null,
  "assignedAt": null,
  "flagCount": 1,
  "openFlagCount": 1,
  "shared": [
    {
      "user": { "userId": 3, "email": "dana@acme.com", "firstName": "Dana", "lastName": null },
      "saved": false,
      "flagged": true,
      "flaggedAt": "2026-06-14T12:00:00.000Z",
      "note": "waiting on counterparty confirmation",
      "noteUpdatedAt": "2026-06-14T12:05:00.000Z",
      "resolvedAt": null,
      "resolvedBy": null,
      "assignedTo": { "userId": 8, "email": "rafa@acme.com", "firstName": "Rafa", "lastName": null },
      "assignedAt": "2026-06-14T12:06:00.000Z"
    }
  ]
}

Sets your own marks (an API key acts as its creator). Only the fields you send change, so the ★, the ⚑ and the note can each be written on their own. Send "" or null as the note to clear it; the row is removed once no mark is left set. Notes are capped at 1000 characters.

curl -X PUT "https://api.guveno.com/v1/transactions/9001/marks" \
  -H "Authorization: Bearer gv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"flagged": true, "note": "unexpected fee, review with finance"}'

A note written without a flag is private: noteShared is false on a first write and kept thereafter, so an integration that leaves it out writes a note only its own key reads back. Send "noteShared": true to show your ★ and its note to the team, with your name; it never changes a raised flag, whose note is always shared.

curl -X PUT "https://api.guveno.com/v1/transactions/9001/marks" \
  -H "Authorization: Bearer gv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"saved": true, "note": "VIP payout", "noteShared": true}'

assignToUserId names the one member the flag is waiting on. They are told once, in the dashboard and by email, so it requires a raised flag and a member who can already see the transaction — anyone else is refused. Send null to clear it. A flag with nobody named notifies nobody; it shows up in the flagged list and the activity log instead.

curl -X PUT "https://api.guveno.com/v1/transactions/9001/marks" \
  -H "Authorization: Bearer gv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"flagged": true, "assignToUserId": 8}'

Reads the same object without fetching the whole transaction.

Counts for the review lists: saved is how many you saved, flagged how many are flagged by anyone whose visibility you share, flaggedOpen how many of those are still waiting on a review, and assignedToMe the open flags someone asked you to look at.

curl "https://api.guveno.com/v1/transactions/marks/summary" \
  -H "Authorization: Bearer gv_live_your_key_here"

{ "saved": 3, "flagged": 5, "flaggedOpen": 2, "assignedToMe": 1 }

To page through a review list, use the marked filter on the list endpoint — it accepts every other filter too:

curl "https://api.guveno.com/v1/transactions?marked=flagged_open&limit=50" \
  -H "Authorization: Bearer gv_live_your_key_here"

Resolving a flag

Closes a flag as reviewed. This is a separate call from setting your own marks because the person who reviews a flag is usually not the one who raised it: pass raisedByUserId to close someone else's flag, or omit it for your own. The flag keeps naming who raised it and records who reviewed it, so "has anyone looked at this" has an answer.

curl -X POST "https://api.guveno.com/v1/transactions/9001/marks/resolve" \
  -H "Authorization: Bearer gv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"raisedByUserId": 3}'

Send {"resolved": false} to put a resolved flag back in the queue. Resolving one that is already resolved changes nothing and notifies nobody a second time, so a retry is safe. Withdrawing a flag (flagged: false) clears its resolution and assignee with it — there is no such thing as a resolved flag that was never raised.