Script to add stock splits and bonuses from Zerodha

[plibither8]

I've created a small script that parses the Corporate Actions Google Sheet provided by Zerodha, takes as input your Zerodha tradebook (downloaded as a CSV), and outputs to the console/STDOUT the various stock splits and bonuses that occurred while you had those shares in your balance, as ledger transactions.

Script files

Steps:

1. Install bun
2. Download your tradebook from Zerodha's console as a CSV file. Since Zerodha allows for max window size of 365 days, you will need to download mutliple CSVs for all the years you've traded, and combine them into a single CSV file.
3. Create a directory where you will save and run this script from.
4. Create a sub-directories called input/ and output/. Place the CSV file into input/. Rename the CSV as tradebook.csv.
5. Get your Google Sheets auth tokens from the Google Console. Follow this guide for better details: https://theoephraim.github.io/node-google-spreadsheet/#/guides/authentication?id=service-account
6. Create a .env file and add the following keys: GOOGLE_SERVICE_ACCOUNT_EMAIL and GOOGLE_PRIVATE_KEY.
7. From the new, parent directory:
   bun install
bun run ./corporate-actions.ts
8. If the run is successful, and it found stock splits and bonuses, they should be output in the console as ledger transactions.
9. Copy the transactions and add them to your journal!

I know that the steps I included seem really convoluted and complicated, but it was worth the effort!

Let me know if anyone has any questions, I'd be happy to answer! :)

[ananthakumaran]

Very nice. I noticed the usage of Equity account Equity:Stocks:${action.symbol}, have you considered using Income:Dividend:Stocks:${action.symbol}? Equity has a different meaning and this is more of a income (like interest, but you get paid via stocks). I have plans to treat Income:Dividend:{name} like I treat Income:Interest:{name} so XIRR would be more accurate.

[plibither8]

Good question. I'm not sure of the correct approach here, but when thinking of bonus stocks in ledger format, the extra stocks usually come from "thin air". They are credited to your broker, but debited from the account books of the company (and it makes no sense to keep track of their specific account). And so I thought the most sensible way to tackle this would be to debit it from "Equity".

Edit: Also, I want to treat bonus stocks differently vs. dividends. I'm not really an expert on this, but are bonus stocks considered "income"?

[ananthakumaran]

It doesn't come from thin air. You are given bonus shares only if you hold the shares and the bonus is proportional to the amount of shares you hold. If you think about it, it has all the features of Dividend, except that instead of INR, you get it as stock. I would say it is your income, which might also have tax implications.

Edit: Also, I want to treat bonus stocks differently vs. dividends. I'm not really an expert on this, but are bonus stocks considered "income"?

I assume it's income, others can share their perspective. From an accounting perspective, if you want to treat them differently, you can use different income accounts for them Income:Dividend:{name}, Income:StockBonus:{name} (just invent a new sub-account under Income`

[plibither8]

I would say it is your income, which might also have tax implications.

Again, I might be wrong and am ready to be corrected here, but I disagree. The bonus shares only have tax implications once they are sold, like any other regular share bought by us. I'll also link this article that discusses a recent ruling stating that bonus shares are not be treated as "Income from other sources", and thus are not taxable.

[goelprateek5]

I have plans to treat Income:Dividend:{name} like I treat Income:Interest:{name} so XIRR would be more accurate.

On an unrelated note, have we documented the special categories that should not be changed to use the application as intended, few that I found - Assets, Investment, Income.

I wonder if I am using something incorrectly.