From 250eda9460217a94e428be4f059b540d38282813 Mon Sep 17 00:00:00 2001
From: Ed Harrod <echarrod@users.noreply.github.com>
Date: Thu, 23 Oct 2025 11:28:56 +0100
Subject: [PATCH 1/3] agents: Add AGENTS.md file

---
 .DS_Store | Bin 6148 -> 8196 bytes
 AGENTS.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |   5 +++
 3 files changed, 118 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/.DS_Store b/.DS_Store
index 9146fe0cb3aab07f6ed8c1130d11342053e9ccd4..cf769f1c5afecc3f7e9a9f4db6ed385df3fd3f2a 100644
GIT binary patch
literal 8196
zcmeHMy=xRf6n}FcdUyz;DX#M%r6hRRXyqlG7Gfdf4>0$U%bo1q29pcg$hLwJJ4t6{
zW1$EN7FIC|78Y7+Cn$;_3Q<dc^KrXxvU``yA!2YQ%)DdYd;9ynH?uSQHbf+5dyNuN
zfrxVGQXa}<NN7?od#t6*l@pKx{zS{(Vrj1Kca~zd?t;sJ%Ye&(%Ye&(%fP>p0i4;g
z<p!MlTI)ua0hfXQG6QmdD56VQHZsssZ5<d?2>_YFW!3N-b%63I8d)|n&{DbLp1OJv
z##NXSLuhyCi_#pjY-FINb|<0TNf=~dDiop6;a61VB+6R4(PhA8Af5qPyJu;d7HAQF
z+v@kzcWiCPuT*NDU&Ga0aO%L%8{YGo?G}w4ES6gQ3&8`pV+WW9cAHkLuLt7(7T0m?
zm9LL32Oku6=-crl<Rra?o0YJ%zmH2T>QT)?r_@^9f^#_g`APG(j(^*IIFrFv79YLo
z$$4l~19MTexlCLG7pCPrUUnxp)}wha{+vUyg^hnp=Hnpnm*^_3fWb1xi&Up7dW#lp
zKB<$#tvSC>?>F;nn%|K7bH1Z_*!<@u|18xok8Sd(Ve@_W+SYP@cS{?E$s;fHIu89g
zpJWRQU!OV|%w1b%&PKl^(L)`_{y1~A{|qsGw2qVX7A~d>Esgo=(ke$4)pNfh4afXm
z3*$9@Jl43D<B7)?Bwh}9SFkcVfcNBDX)M>hn(upwN=}Pt-?5|{aDrc&Z=aftB?iQ)
z4zuH=%?n8$RC`F1k7cbFc?-Y0ocaJ0JAlnD0vKS)!<hPZ{f7x-pmj9UJ6l^J>6f61
z<dE<b>)m_`tFcQ>^6d!H4-vu0zC5O_)o1HB^|QPS|0v3F{H?f2t-oxzLs=`2UA6;0
z{0adxEf4AZn|uB3$+Cz@CtKLGjssxtwX~*OkoEtW!QcP)USN)~%Ye(k$Qcls%3Ng@
z=BBoeIm%kQh(3=lo3snGR4y1)IS#4Hamer=hWK5Csq`ru8EA<sXn+4hfII(@_FbIc
Zm9U~4=ltfcY~%Rb2dz8*)kE_KhTn7%M`!>5

delta 136
zcmZp1XfcprU|?W$DortDU=RQ@Ie-{MGqg`E6q~50D9Q|EGlInm7;+d=8H!VilXE5(
zsxvZAwh>X7EG{ZOnOl@+@_sS#jirk0i`h9i1VLJWK!6)axB_we#=`H+llf%~85t(q
T@JRD8L97AU%&<A0XAUy}G|v}2

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4095d2c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,113 @@
+# AGENTS.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the **Luno Python SDK**, a wrapper for the Luno API (cryptocurrency exchange platform). The package provides a Python client for interacting with Luno's REST API, supporting operations like account management, trading, fund transfers, and market data queries.
+
+## Architecture Overview
+
+### Core Structure
+
+- **`luno_python/base_client.py`**: Base HTTP client class (`BaseClient`) that handles:
+  - HTTP requests using the `requests` library
+  - Basic auth with API key and secret
+  - Error handling and JSON parsing
+  - User-Agent generation
+  - URL construction with parameter substitution
+
+- **`luno_python/client.py`**: Main `Client` class extending `BaseClient`. Contains ~100+ API methods auto-generated from the Luno API specification. Each method:
+  - Wraps a specific API endpoint
+  - Constructs the request object with parameters
+  - Calls `do()` to make the HTTP request
+  - Returns the API response as a dictionary
+
+- **`luno_python/error.py`**: Custom `APIError` exception class for handling API errors
+
+- **`luno_python/__init__.py`**: Exports package version
+
+### Request/Response Flow
+
+1. User calls a method on `Client` (e.g., `get_ticker(pair='XBTZAR')`)
+2. Method builds a request dict with parameters
+3. Method calls `self.do(method, path, req, auth)` from `BaseClient`
+4. `do()` makes HTTP request via `requests.Session`
+5. `do()` parses JSON response and checks for API error codes
+6. If error found, raises `APIError`; otherwise returns response dict
+
+### API Design Patterns
+
+- **Authentication**: HTTP Basic Auth with `api_key_id` and `api_key_secret`
+- **Path parameters**: Substituted using `{param_name}` syntax in paths
+- **Query parameters**: Passed via `params` in GET requests
+- **Error handling**: API returns `{"error_code": "...", "error": "..."}` on errors
+
+## Development Commands
+
+### Setup
+
+```bash
+# Create and activate virtual environment
+python -m venv env
+source env/bin/activate  # On Windows: env\Scripts\activate
+
+# Install package in development mode with test dependencies
+pip install -e '.[test]'
+```
+
+### Testing
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/test_client.py
+
+# Run specific test
+pytest tests/test_client.py::test_client_do_basic
+
+# Run with verbose output
+pytest -v
+
+# Run with coverage
+pytest --cov=luno_python
+```
+
+### Dependencies
+
+- **Runtime**: `requests>=2.18.4`, `six>=1.11.0`
+- **Test**: `pytest`, `pytest-cov`, `requests_mock`
+
+## Testing Approach
+
+Tests use `requests_mock` to mock HTTP responses. The pattern:
+
+1. Create a `Client` instance
+2. Mount mock adapter to session: `adapter.register_uri(method, url, ...)`
+3. Call client method and assert response
+
+Recent additions test the `get_balances()` method with `account_id` parameter for filtering results by account.
+
+## Git Workflow
+
+When making changes:
+
+1. Run `git pull` before creating a new branch
+2. Branch naming: `{username}-{issue-number}-{description}`
+3. Commit messages: Present tense, describe *why* not *what*
+4. Example: `"client: Add account_id parameter to get_balances method"`
+5. Push and create PR when ready
+
+## Notes on Code Generation
+
+The `client.py` file contains ~100+ methods that are auto-generated from Luno's API specification. When modifying or adding methods:
+
+- Follow existing docstring format (includes HTTP method, path, permissions, parameter descriptions)
+- Each method constructs a `req` dict with parameters and calls `self.do()`
+- Type hints in docstrings use `:type param: type_name` format for Python 2 compatibility
+
+## File Editing Requirements
+
+Always ensure files end with a newline character. This maintains consistency with Git diffs and repository standards.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..ccc05ab
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+For compatibility with multiple agents, the instructions are located at @AGENTS.md (see [AGENTS.md](./AGENTS.md).

From 8a324fd78e09fb116d064d49662da47eaf90f367 Mon Sep 17 00:00:00 2001
From: Ed Harrod <echarrod@users.noreply.github.com>
Date: Thu, 23 Oct 2025 11:56:04 +0100
Subject: [PATCH 2/3] Apply suggestion from @echarrod

---
 AGENTS.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 4095d2c..e6bfdd5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to agents (e.g. Claude Code / GitHub CoPilot) when working with code in this repository.
 
 ## Project Overview
 

From 1509e244c53c129da9957a4e3ca67a20b27575c4 Mon Sep 17 00:00:00 2001
From: Ed Harrod <echarrod@users.noreply.github.com>
Date: Thu, 23 Oct 2025 11:58:35 +0100
Subject: [PATCH 3/3] gitignore: Remove .DS_STORE

---
 .DS_Store | Bin 8196 -> 0 bytes
 1 file changed, 0 insertions(+), 0 deletions(-)
 delete mode 100644 .DS_Store

diff --git a/.DS_Store b/.DS_Store
deleted file mode 100644
index cf769f1c5afecc3f7e9a9f4db6ed385df3fd3f2a..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 8196
zcmeHMy=xRf6n}FcdUyz;DX#M%r6hRRXyqlG7Gfdf4>0$U%bo1q29pcg$hLwJJ4t6{
zW1$EN7FIC|78Y7+Cn$;_3Q<dc^KrXxvU``yA!2YQ%)DdYd;9ynH?uSQHbf+5dyNuN
zfrxVGQXa}<NN7?od#t6*l@pKx{zS{(Vrj1Kca~zd?t;sJ%Ye&(%Ye&(%fP>p0i4;g
z<p!MlTI)ua0hfXQG6QmdD56VQHZsssZ5<d?2>_YFW!3N-b%63I8d)|n&{DbLp1OJv
z##NXSLuhyCi_#pjY-FINb|<0TNf=~dDiop6;a61VB+6R4(PhA8Af5qPyJu;d7HAQF
z+v@kzcWiCPuT*NDU&Ga0aO%L%8{YGo?G}w4ES6gQ3&8`pV+WW9cAHkLuLt7(7T0m?
zm9LL32Oku6=-crl<Rra?o0YJ%zmH2T>QT)?r_@^9f^#_g`APG(j(^*IIFrFv79YLo
z$$4l~19MTexlCLG7pCPrUUnxp)}wha{+vUyg^hnp=Hnpnm*^_3fWb1xi&Up7dW#lp
zKB<$#tvSC>?>F;nn%|K7bH1Z_*!<@u|18xok8Sd(Ve@_W+SYP@cS{?E$s;fHIu89g
zpJWRQU!OV|%w1b%&PKl^(L)`_{y1~A{|qsGw2qVX7A~d>Esgo=(ke$4)pNfh4afXm
z3*$9@Jl43D<B7)?Bwh}9SFkcVfcNBDX)M>hn(upwN=}Pt-?5|{aDrc&Z=aftB?iQ)
z4zuH=%?n8$RC`F1k7cbFc?-Y0ocaJ0JAlnD0vKS)!<hPZ{f7x-pmj9UJ6l^J>6f61
z<dE<b>)m_`tFcQ>^6d!H4-vu0zC5O_)o1HB^|QPS|0v3F{H?f2t-oxzLs=`2UA6;0
z{0adxEf4AZn|uB3$+Cz@CtKLGjssxtwX~*OkoEtW!QcP)USN)~%Ye(k$Qcls%3Ng@
z=BBoeIm%kQh(3=lo3snGR4y1)IS#4Hamer=hWK5Csq`ru8EA<sXn+4hfII(@_FbIc
Zm9U~4=ltfcY~%Rb2dz8*)kE_KhTn7%M`!>5