From 96300f5e5b5f32e6b6d5d1de4bf9cccdc1c8dd6f Mon Sep 17 00:00:00 2001
From: Elisabeth Duijnstee <elisabethduijnstee@elisabeths-air.home>
Date: Sat, 22 Nov 2025 17:08:40 +0000
Subject: [PATCH] Add create earn account use case (v2)

- Add TypeScript example for creating Earn Account on Base
- Add Python example for creating Earn Account on Base
- Include README files for both languages
- Example demonstrates getting unsigned transaction (no gas sponsorship)
- Requires compass-api-sdk v2.0.1+ for Python
---
 v2/create_earn_account/TESTING.md             | 63 +++++++++++++++++++
 v2/create_earn_account/python/.env.example    |  6 ++
 v2/create_earn_account/python/README.md       | 49 +++++++++++++++
 v2/create_earn_account/python/main.py         | 34 ++++++++++
 v2/create_earn_account/python/pyproject.toml  |  9 +++
 .../typescript/.env.example                   |  6 ++
 v2/create_earn_account/typescript/README.md   | 47 ++++++++++++++
 .../typescript/package.json                   | 25 ++++++++
 .../typescript/src/index.ts                   | 34 ++++++++++
 .../typescript/tsconfig.json                  | 17 +++++
 10 files changed, 290 insertions(+)
 create mode 100644 v2/create_earn_account/TESTING.md
 create mode 100644 v2/create_earn_account/python/.env.example
 create mode 100644 v2/create_earn_account/python/README.md
 create mode 100644 v2/create_earn_account/python/main.py
 create mode 100644 v2/create_earn_account/python/pyproject.toml
 create mode 100644 v2/create_earn_account/typescript/.env.example
 create mode 100644 v2/create_earn_account/typescript/README.md
 create mode 100644 v2/create_earn_account/typescript/package.json
 create mode 100644 v2/create_earn_account/typescript/src/index.ts
 create mode 100644 v2/create_earn_account/typescript/tsconfig.json

diff --git a/v2/create_earn_account/TESTING.md b/v2/create_earn_account/TESTING.md
new file mode 100644
index 00000000..106046d3
--- /dev/null
+++ b/v2/create_earn_account/TESTING.md
@@ -0,0 +1,63 @@
+# Testing Guide
+
+Test both TypeScript and Python versions before pushing.
+
+## Prerequisites
+
+1. Create `.env` files in both directories with your actual values:
+   - `COMPASS_API_KEY`: Your Compass API key
+   - `WALLET_ADDRESS`: Your wallet address (0x...)
+
+## Test TypeScript
+
+```bash
+cd typescript
+
+# Make sure .env file exists (copy from .env.example and fill in values)
+cp .env.example .env
+# Edit .env with your actual values
+
+# Run the script
+npm run dev
+```
+
+**Expected output:**
+- Earn Account Address: `0x...`
+- Unsigned Transaction: `{ chainId, data, from, gas, ... }`
+
+## Test Python
+
+```bash
+cd python
+
+# Install dependencies (if using uv or pip)
+pip install compass-api-sdk python-dotenv
+# OR if using uv:
+# uv pip install compass-api-sdk python-dotenv
+
+# Make sure .env file exists
+cp .env.example .env
+# Edit .env with your actual values
+
+# Run the script
+python main.py
+```
+
+**Expected output:**
+- Earn Account Address: `0x...`
+- Unsigned Transaction: `{ chainId, data, from, gas, ... }`
+
+## Verify Results
+
+Both scripts should:
+1. ✅ Successfully connect to Compass API
+2. ✅ Return an Earn Account address
+3. ✅ Return an unsigned transaction object
+4. ✅ No errors
+
+If you get errors, check:
+- API key is valid
+- Wallet address is correct format (0x...)
+- Network connection
+- SDK versions are up to date
+
diff --git a/v2/create_earn_account/python/.env.example b/v2/create_earn_account/python/.env.example
new file mode 100644
index 00000000..ee1b4cd7
--- /dev/null
+++ b/v2/create_earn_account/python/.env.example
@@ -0,0 +1,6 @@
+# Compass API Configuration
+COMPASS_API_KEY=your_compass_api_key_here
+
+# Wallet Configuration
+# The wallet address that will own the Earn Account and pay for gas
+WALLET_ADDRESS=0xYourWalletAddress
diff --git a/v2/create_earn_account/python/README.md b/v2/create_earn_account/python/README.md
new file mode 100644
index 00000000..108b31e0
--- /dev/null
+++ b/v2/create_earn_account/python/README.md
@@ -0,0 +1,49 @@
+# Create Earn Account - Python Example
+
+This example demonstrates how to create an Earn Account using the Compass API Python SDK.
+
+## Prerequisites
+
+- Python 3.9+ installed
+- A Compass API key ([Get one here](https://auth-compasslabs-ai.auth.eu-west-2.amazoncognito.com/login?client_id=2l366l2b3dok7k71nbnu8r1u36&redirect_uri=https://api.compasslabs.ai/auth/callback&response_type=code&scope=openid+email+profile))
+
+## Setup
+
+1. Install dependencies (make sure you have the latest version):
+```bash
+pip install --upgrade compass-api-sdk python-dotenv
+```
+
+Or if using `uv`:
+```bash
+uv pip install compass-api-sdk python-dotenv
+```
+
+**Note:** This example requires `compass-api-sdk` version 2.0.1 or later (which includes the `earn` endpoints). Make sure to upgrade if you have an older version.
+
+2. Copy the example environment file:
+```bash
+cp .env.example .env
+```
+
+3. Fill in your `.env` file with your actual values:
+   - `COMPASS_API_KEY`: Your Compass API key
+   - `WALLET_ADDRESS`: Your wallet address (will own the Earn Account)
+
+## Run
+
+```bash
+python main.py
+```
+
+## What This Does
+
+This example gets an unsigned transaction to create an Earn Account on Base. The transaction must be signed and broadcast separately.
+
+## Notes
+
+- **No Gas Sponsorship**: The `owner` (who controls the account) is also the `sender` (who pays for gas). Note that Earn Account creation can also be done WITH gas sponsorship (using the `/gas_sponsorship/prepare` endpoint), but this example does not use gas sponsorship.
+- The Earn Account address is deterministic and returned before the transaction is confirmed.
+- This example only retrieves the unsigned transaction. You'll need to sign and broadcast it separately.
+- **Important:** Requires `compass-api-sdk` version 2.0.1 or later (includes `earn` endpoints). Make sure to install the latest version.
+
diff --git a/v2/create_earn_account/python/main.py b/v2/create_earn_account/python/main.py
new file mode 100644
index 00000000..068581f0
--- /dev/null
+++ b/v2/create_earn_account/python/main.py
@@ -0,0 +1,34 @@
+# SNIPPET START 1
+# Import Libraries & Environment Variables
+from compass_api_sdk import CompassAPI, models
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+COMPASS_API_KEY = os.getenv("COMPASS_API_KEY")
+WALLET_ADDRESS = os.getenv("WALLET_ADDRESS")
+# SNIPPET END 1
+
+# SNIPPET START 2
+# Initialize Compass SDK
+compass = CompassAPI(api_key_auth=COMPASS_API_KEY)
+# SNIPPET END 2
+
+# SNIPPET START 3
+# Create Earn Account (No Gas Sponsorship)
+# Get unsigned transaction to create an Earn Account on Base
+# owner: The address that will own and control the Earn Account
+# sender: The address that will sign and pay for gas (same as owner = no gas sponsorship)
+with CompassAPI(api_key_auth=COMPASS_API_KEY) as compass_api:
+    create_account_response = compass_api.earn.earn_create_account(
+        chain=models.CreateAccountRequestChain.BASE,
+        sender=WALLET_ADDRESS,
+        owner=WALLET_ADDRESS,
+        estimate_gas=True,
+    )
+
+    print("Earn Account Address:", create_account_response.earn_account_address)
+    print("Unsigned Transaction:", create_account_response.transaction)
+# SNIPPET END 3
+
diff --git a/v2/create_earn_account/python/pyproject.toml b/v2/create_earn_account/python/pyproject.toml
new file mode 100644
index 00000000..32261017
--- /dev/null
+++ b/v2/create_earn_account/python/pyproject.toml
@@ -0,0 +1,9 @@
+[project]
+name = "create_earn_account_python_example"
+version = "1.0.0"
+description = "Example: Create an Earn Account using Compass API"
+dependencies = [
+    "compass-api-sdk",
+    "python-dotenv",
+]
+
diff --git a/v2/create_earn_account/typescript/.env.example b/v2/create_earn_account/typescript/.env.example
new file mode 100644
index 00000000..ee1b4cd7
--- /dev/null
+++ b/v2/create_earn_account/typescript/.env.example
@@ -0,0 +1,6 @@
+# Compass API Configuration
+COMPASS_API_KEY=your_compass_api_key_here
+
+# Wallet Configuration
+# The wallet address that will own the Earn Account and pay for gas
+WALLET_ADDRESS=0xYourWalletAddress
diff --git a/v2/create_earn_account/typescript/README.md b/v2/create_earn_account/typescript/README.md
new file mode 100644
index 00000000..7ce4ab4a
--- /dev/null
+++ b/v2/create_earn_account/typescript/README.md
@@ -0,0 +1,47 @@
+# Create Earn Account - TypeScript Example
+
+This example demonstrates how to create an Earn Account using the Compass API TypeScript SDK.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- A Compass API key ([Get one here](https://auth-compasslabs-ai.auth.eu-west-2.amazoncognito.com/login?client_id=2l366l2b3dok7k71nbnu8r1u36&redirect_uri=https://api.compasslabs.ai/auth/callback&response_type=code&scope=openid+email+profile))
+
+## Setup
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Copy the example environment file:
+```bash
+cp .env.example .env
+```
+
+3. Fill in your `.env` file with your actual values:
+   - `COMPASS_API_KEY`: Your Compass API key
+   - `WALLET_ADDRESS`: Your wallet address (will own the Earn Account)
+
+## Run
+
+```bash
+npm run dev
+```
+
+Or build and run:
+```bash
+npm run build
+npm start
+```
+
+## What This Does
+
+This example gets an unsigned transaction to create an Earn Account on Base. The transaction must be signed and broadcast separately.
+
+## Notes
+
+- **No Gas Sponsorship**: The `owner` (who controls the account) is also the `sender` (who pays for gas). Note that Earn Account creation can also be done WITH gas sponsorship (using the `/gas_sponsorship/prepare` endpoint), but this example does not use gas sponsorship.
+- The Earn Account address is deterministic and returned before the transaction is confirmed.
+- This example only retrieves the unsigned transaction. You'll need to sign and broadcast it separately.
+
diff --git a/v2/create_earn_account/typescript/package.json b/v2/create_earn_account/typescript/package.json
new file mode 100644
index 00000000..7c9598c5
--- /dev/null
+++ b/v2/create_earn_account/typescript/package.json
@@ -0,0 +1,25 @@
+{
+  "name": "create_earn_account_typescript_example",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "tsc && node dist/index.js",
+    "dev": "ts-node --esm src/index.ts"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": "Example: Create an Earn Account using Compass API",
+  "dependencies": {
+    "@compass-labs/api-sdk": "^1.0.26",
+    "dotenv": "^16.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "prettier": "^3.6.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3"
+  }
+}
+
diff --git a/v2/create_earn_account/typescript/src/index.ts b/v2/create_earn_account/typescript/src/index.ts
new file mode 100644
index 00000000..3c693031
--- /dev/null
+++ b/v2/create_earn_account/typescript/src/index.ts
@@ -0,0 +1,34 @@
+// SNIPPET START 1
+// Import Libraries & Environment Variables
+import { CompassApiSDK } from "@compass-labs/api-sdk";
+import dotenv from "dotenv";
+
+dotenv.config();
+
+const COMPASS_API_KEY = process.env.COMPASS_API_KEY as string;
+const WALLET_ADDRESS = process.env.WALLET_ADDRESS as `0x${string}`;
+// SNIPPET END 1
+
+// SNIPPET START 2
+// Initialize Compass SDK
+const compass = new CompassApiSDK({
+  apiKeyAuth: COMPASS_API_KEY,
+});
+// SNIPPET END 2
+
+// SNIPPET START 3
+// Create Earn Account (No Gas Sponsorship)
+// Get unsigned transaction to create an Earn Account on Base
+// owner: The address that will own and control the Earn Account
+// sender: The address that will sign and pay for gas (same as owner = no gas sponsorship)
+const createAccountResponse = await compass.earn.earnCreateAccount({
+  chain: "base",
+  sender: WALLET_ADDRESS,
+  owner: WALLET_ADDRESS,
+  estimateGas: true,
+});
+
+console.log("Earn Account Address:", createAccountResponse.earnAccountAddress);
+console.log("Unsigned Transaction:", createAccountResponse.transaction);
+// SNIPPET END 3
+
diff --git a/v2/create_earn_account/typescript/tsconfig.json b/v2/create_earn_account/typescript/tsconfig.json
new file mode 100644
index 00000000..e1de2baf
--- /dev/null
+++ b/v2/create_earn_account/typescript/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "es2020",
+    "lib": ["es2020"],
+    "module": "nodenext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}
+