Buy and sell shares

Set up a security and a brokerage account, record a purchase with its commission, record a sale with the realised gain, and keep the share price up to date.

Shares are a commodity that is not a currency. A holding of shares is an account of type STOCK whose commodity is the security, so its balance counts shares, not dollars. In a transaction, the share account's split has an amount in shares and a value in the transaction's currency: ten shares at 150.00 are an amount of 10 and a value of 1,500.00.

Steps

Create the security with commodity.create: a namespace (the exchange, such as NASDAQ), a mnemonic (the ticker) and a fullname.
Create the accounts. A brokerage placeholder (ASSET), a cash account for it (BANK), a STOCK account per security with commodity set to the security's ID (NASDAQ::AAPL), an expense for commissions and an income account for realised gains.
Buy. transaction.post in the cash account's currency (set currency, since the first split may be in shares): the share account +value with amount in shares, the commission expense +, and the cash account - for the total.
Record the price with price.add, the commodity priced in the currency, so reports can value the holding. A buy or sell in the register records its price too if you pass recordPrice: true.
Sell. The cash account gets the proceeds less commission. The share account is credited at what the shares cost (the shares' amount negative, their value the cost basis). The difference between proceeds and cost is the realised gain, credited to the gains income account, or debited if it is a loss.
Check the number of shares with account.balance; the balance is in shares.

For which shares were sold, with several purchases at different prices, see Capital gains with lots.

Example

Buy 10 shares at 150.00 with a 9.95 commission, then sell 4 at 160.00. The cost of the 4 is 600.00; they are sold for 640.00, a gain of 40.00.

Example: with a new, empty book open as book.gnucash, at 2024-07-31T12:00:00Z.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"commodity.create","params":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "NASDAQ::AAPL",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Brokerage","type":"ASSET","commodity":"USD","placeholder":true}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Cash","type":"BANK","parent":"Brokerage"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":4,"method":"account.create","params":{"name":"AAPL","type":"STOCK","parent":"Brokerage","commodity":"NASDAQ::AAPL"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "commodity": "NASDAQ::AAPL",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":5,"method":"account.create","params":{"name":"Commissions","type":"EXPENSE","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":6,"method":"account.create","params":{"name":"Realised gains","type":"INCOME","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":7,"method":"account.create","params":{"name":"Opening Balances","type":"EQUITY","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":8,"method":"transaction.post","params":{"datePosted":"2024-07-01","description":"Deposit","splits":[{"account":"Brokerage:Cash","value":"5000.00"},{"account":"Opening Balances","value":"-5000.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":9,"method":"transaction.post","params":{"datePosted":"2024-07-02","description":"Buy AAPL","currency":"USD","splits":[{"account":"Brokerage:AAPL","value":"1500.00","amount":"10"},{"account":"Commissions","value":"9.95"},{"account":"Brokerage:Cash","value":"-1509.95"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 9,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":10,"method":"price.add","params":{"commodity":"NASDAQ::AAPL","currency":"USD","value":"160.00","date":"2024-07-15"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "outcome": "added",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":11,"method":"transaction.post","params":{"datePosted":"2024-07-15","description":"Sell AAPL","currency":"USD","splits":[{"account":"Brokerage:Cash","value":"630.05"},{"account":"Commissions","value":"9.95"},{"account":"Brokerage:AAPL","value":"-600.00","amount":"-4"},{"account":"Realised gains","value":"-40.00"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "balanced": true,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":12,"method":"account.balance","params":{"account":"Brokerage:AAPL"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 12,
  "result": {
    "balances": {
      "commodity": "NASDAQ::AAPL",
      "balance": {
        "num": "60000",
        "denom": "10000"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":13,"method":"account.balance","params":{"account":"Brokerage:Cash"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 13,
  "result": {
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "412010",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
commodity.create {"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}
account.create {"name":"Brokerage","type":"ASSET","commodity":"USD","placeholder":true}
account.create {"name":"Cash","type":"BANK","parent":"Brokerage"}
account.create {"name":"AAPL","type":"STOCK","parent":"Brokerage","commodity":"NASDAQ::AAPL"}
account.create {"name":"Commissions","type":"EXPENSE","commodity":"USD"}
account.create {"name":"Realised gains","type":"INCOME","commodity":"USD"}
account.create {"name":"Opening Balances","type":"EQUITY","commodity":"USD"}
transaction.post {"datePosted":"2024-07-01","description":"Deposit","splits":[{"account":"Brokerage:Cash","value":"5000.00"},{"account":"Opening Balances","value":"-5000.00"}]}
transaction.post {"datePosted":"2024-07-02","description":"Buy AAPL","currency":"USD","splits":[{"account":"Brokerage:AAPL","value":"1500.00","amount":"10"},{"account":"Commissions","value":"9.95"},{"account":"Brokerage:Cash","value":"-1509.95"}]}
price.add {"commodity":"NASDAQ::AAPL","currency":"USD","value":"160.00","date":"2024-07-15"}
transaction.post {"datePosted":"2024-07-15","description":"Sell AAPL","currency":"USD","splits":[{"account":"Brokerage:Cash","value":"630.05"},{"account":"Commissions","value":"9.95"},{"account":"Brokerage:AAPL","value":"-600.00","amount":"-4"},{"account":"Realised gains","value":"-40.00"}]}
account.balance {"account":"Brokerage:AAPL"}
account.balance {"account":"Brokerage:Cash"}
EOF

It prints:

[
  {
    "id": "NASDAQ::AAPL",
    "…": "…"
  },
  "…",
  "…",
  {
    "commodity": "NASDAQ::AAPL",
    "…": "…"
  },
  "…",
  "…",
  "…",
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balanced": true,
    "…": "…"
  },
  {
    "outcome": "added",
    "…": "…"
  },
  {
    "balanced": true,
    "…": "…"
  },
  {
    "balances": {
      "commodity": "NASDAQ::AAPL",
      "balance": {
        "num": "60000",
        "denom": "10000"
      },
      "…": "…"
    },
    "…": "…"
  },
  {
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "412010",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"commodity.create","arguments":{"namespace":"NASDAQ","mnemonic":"AAPL","fullname":"Apple Inc"}}

Result:

{
  "structuredContent": {
    "id": "NASDAQ::AAPL",
    "…": "…"
  }
}

Tool call:

{"name":"account.create","arguments":{"name":"Brokerage","type":"ASSET","commodity":"USD","placeholder":true}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Cash","type":"BANK","parent":"Brokerage"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"AAPL","type":"STOCK","parent":"Brokerage","commodity":"NASDAQ::AAPL"}}

Result:

{
  "structuredContent": {
    "commodity": "NASDAQ::AAPL",
    "…": "…"
  }
}

Tool call:

{"name":"account.create","arguments":{"name":"Commissions","type":"EXPENSE","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Realised gains","type":"INCOME","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"account.create","arguments":{"name":"Opening Balances","type":"EQUITY","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-01","description":"Deposit","splits":[{"account":"Brokerage:Cash","value":"5000.00"},{"account":"Opening Balances","value":"-5000.00"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-02","description":"Buy AAPL","currency":"USD","splits":[{"account":"Brokerage:AAPL","value":"1500.00","amount":"10"},{"account":"Commissions","value":"9.95"},{"account":"Brokerage:Cash","value":"-1509.95"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"price.add","arguments":{"commodity":"NASDAQ::AAPL","currency":"USD","value":"160.00","date":"2024-07-15"}}

Result:

{
  "structuredContent": {
    "outcome": "added",
    "…": "…"
  }
}

Tool call:

{"name":"transaction.post","arguments":{"datePosted":"2024-07-15","description":"Sell AAPL","currency":"USD","splits":[{"account":"Brokerage:Cash","value":"630.05"},{"account":"Commissions","value":"9.95"},{"account":"Brokerage:AAPL","value":"-600.00","amount":"-4"},{"account":"Realised gains","value":"-40.00"}]}}

Result:

{
  "structuredContent": {
    "balanced": true,
    "…": "…"
  }
}

Tool call:

{"name":"account.balance","arguments":{"account":"Brokerage:AAPL"}}

Result:

{
  "structuredContent": {
    "balances": {
      "commodity": "NASDAQ::AAPL",
      "balance": {
        "num": "60000",
        "denom": "10000"
      },
      "…": "…"
    },
    "…": "…"
  }
}

Tool call:

{"name":"account.balance","arguments":{"account":"Brokerage:Cash"}}

Result:

{
  "structuredContent": {
    "balances": {
      "commodity": "CURRENCY::USD",
      "balance": {
        "num": "412010",
        "denom": "100"
      },
      "…": "…"
    },
    "…": "…"
  }
}