transaction.transfer

Transfer between two accounts, at a rate when their commodities differ, recording the price.

GnuCash's Transfer dialog as a call: moves amount from one account to another in a two-split transaction. The from account must hold a currency. When the two accounts are in different commodities, give the rate (units of the to commodity per unit of the from currency) or the toAmount received, or leave both out and red-ale uses the price database's price for the date; with no price at all the transfer is refused. The rate is recorded as a price unless recordPrice is false.

The result gives the transaction, the amount received, the rate and what happened to the price (created, updated or kept). The same account on both sides, a placeholder account, a zero amount and a zero or negative rate are refused with invalid.

Examples

Moving 100.00 USD to a pound account at 0.80:

Example: with a copy of the reports/test-data example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"transaction.transfer","params":{"from":"Root:Asset:Bank","to":"Root:Asset:GBP Bank","amount":"100.00","date":"2024-06-10","description":"Top up","rate":"0.80"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transaction": {
      "currency": "CURRENCY::USD",
      "description": "Top up",
      "splits": [
        {
          "accountName": "Root:Asset:GBP Bank",
          "value": {
            "num": "10000",
            "denom": "100"
          },
          "amount": {
            "num": "8000",
            "denom": "100"
          },
          "…": "…"
        },
        {
          "accountName": "Root:Asset:Bank",
          "value": {
            "num": "-10000",
            "denom": "100"
          },
          "…": "…"
        }
      ],
      "…": "…"
    },
    "toAmount": {
      "num": "8000",
      "denom": "100"
    },
    "rate": {
      "num": "80",
      "denom": "100"
    },
    "price": {
      "action": "created",
      "guid": "…"
    }
  }
}

Command line

red-ale exec --book book.gnucash transaction.transfer '{"from":"Root:Asset:Bank","to":"Root:Asset:GBP Bank","amount":"100.00","date":"2024-06-10","description":"Top up","rate":"0.80"}'

It prints:

{
  "transaction": {
    "currency": "CURRENCY::USD",
    "description": "Top up",
    "splits": [
      {
        "accountName": "Root:Asset:GBP Bank",
        "value": {
          "num": "10000",
          "denom": "100"
        },
        "amount": {
          "num": "8000",
          "denom": "100"
        },
        "…": "…"
      },
      {
        "accountName": "Root:Asset:Bank",
        "value": {
          "num": "-10000",
          "denom": "100"
        },
        "…": "…"
      }
    ],
    "…": "…"
  },
  "toAmount": {
    "num": "8000",
    "denom": "100"
  },
  "rate": {
    "num": "80",
    "denom": "100"
  },
  "price": {
    "action": "created",
    "guid": "…"
  }
}

MCP tool call

Tool call:

{"name":"transaction.transfer","arguments":{"from":"Root:Asset:Bank","to":"Root:Asset:GBP Bank","amount":"100.00","date":"2024-06-10","description":"Top up","rate":"0.80"}}

Result:

{
  "structuredContent": {
    "transaction": {
      "currency": "CURRENCY::USD",
      "description": "Top up",
      "splits": [
        {
          "accountName": "Root:Asset:GBP Bank",
          "value": {
            "num": "10000",
            "denom": "100"
          },
          "amount": {
            "num": "8000",
            "denom": "100"
          },
          "…": "…"
        },
        {
          "accountName": "Root:Asset:Bank",
          "value": {
            "num": "-10000",
            "denom": "100"
          },
          "…": "…"
        }
      ],
      "…": "…"
    },
    "toAmount": {
      "num": "8000",
      "denom": "100"
    },
    "rate": {
      "num": "80",
      "denom": "100"
    },
    "price": {
      "action": "created",
      "guid": "…"
    }
  }
}

Effect: write, on the Book.

Params

Params of transaction.transfer.

from (AccountRef, required): The account the amount leaves; it must hold a currency.
to (AccountRef, required): The account it reaches.
amount (Amount, required): The amount, in the from account's currency; not zero.
date (Date or null): The posted date; today by default.
description (string or null): Description.
num (string or null): Num.
notes (string or null): Notes.
memo (string or null): Memo, on both splits.
rate (Amount or null): When the commodities differ: units of the to commodity per unit of the from currency. The amount received is amount × rate rounded half up to the to account's SCU.
toAmount (Amount or null): When the commodities differ: the amount received, in the to commodity; the rate is computed from it. Give rate or toAmount, or neither to use the rate the price database gives on the date (or the nearest one).
recordPrice (boolean): Record the rate in the price database, as the dialog does. True by default.
defaultCurrency (CommodityId or null): The user's default currency (a GnuCash preference): a new price between it and another currency is stored as the other currency priced in it.

Result

The result of transaction.transfer.

transaction (TransactionInfo, required): The transaction created.
toAmount (Amount, required): The amount received, in the to commodity.
rate (Amount or null): The rate used, when the commodities differ.
price (PriceChangeInfo or null): The price recorded, when the commodities differ.