> Guveno API reference v1.10.0, last updated October 17, 2026. The whole reference is at https://www.guveno.com/llms-full.txt.

## Transactions

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

### List transactions

**GET** `/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

**GET** `/transactions/:id`

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"
    }
  ]
}
```

**PUT** `/transactions/:id/marks`

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}'
```

**GET** `/transactions/:id/marks`

Reads the same object without fetching the whole transaction.

**GET** `/transactions/marks/summary`

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

**POST** `/transactions/:id/marks/resolve`

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.

> Reading and writing marks — including resolving someone else's flag — needs only `transactions:read`. A mark moves no money and changes no chain record, and the roles that most want to flag and review things (reviewers, accountants) are read-only by design.

Source: https://www.guveno.com/docs/transactions/