FreelanceLedger

Inspiration

Indian freelancers paid through PayPal in dollars, euros or pounds juggle three recurring chores: converting every payment to rupees, watching the GST registration threshold (INR 20 lakh for most services), and keeping the e-FIRA/FIRC paperwork for each foreign remittance. It usually lives in a messy spreadsheet.

What it does

FreelanceLedger reads a freelancer's PayPal payments and converts each to INR at the ECB reference rate for the payment date. It tracks fees and progress through the Indian financial year (April–March) against the GST threshold, and lists foreign payments that still lack e-FIRA/FIRC paperwork. Gemini categorises each payment and explains the position in plain language, and an "Ask your ledger" box answers questions such as "which payments still need paperwork, and which client paid the most?", using only the ledger data.

How we use PayPal

• OAuth2 client credentials against the PayPal sandbox (the build refuses live mode).
• The Orders API to create and capture test payments.
• The Transaction Search API (/v1/reporting/transactions) to read completed payments with their fees, filtered to received-payment event codes.
• Transaction Search can lag behind new payments, so the app also reads the orders it created and merges both without duplicates.

How we use AI

Google Gemini (gemini-3.5-flash-lite, free tier) through an OpenAI-compatible interface handles payment categorisation, plain-language explanation and ledger Q&A. Results are cached and the Ask box is rate-limited. If no model is configured, the app falls back to deterministic rules and shows which engine produced each result. Any OpenAI-compatible endpoint or Claude can be swapped in.

How we built it

Python and FastAPI back end, a single-page front end with AG Grid Community for the payments table, Frankfurter (ECB) for FX rates, deployed on Render, with 15 automated tests. The demo video was generated by a script that drives the real app and records the screen.

Challenges

Sandbox accounts and currencies (USD payments need a US sandbox buyer), Transaction Search permissions and lag, separating real income from funding rows (event code T19xx), and keeping the AI honest: it answers only from ledger data and sends tax questions to a CA.

Accomplishments

A working end-to-end flow from a real sandbox payment to INR, threshold and paperwork status. The app still works with no AI key. It is tested and open source (MIT).

What we learned

Real payment data is messy: fees, currencies, event codes and reporting delays all need handling before the numbers can be trusted.

What's next

PayPal Invoicing and webhooks for real-time updates, multi-year history, export for a CA, and other payment sources.

Record-keeping tool, not tax advice. Demo data is fictional. Built with help from an AI coding assistant.

Built With

• ag-grid
• css
• fastapi
• google-gemini
• html
• http
• javascript
• paypal
• pytest
• python
• render
• uvicorn