Skill: aaronahadi23/taxguard-skill (version 1.1.0)

# Rhetra TaxGuard Your trading bot's tax advisor. Silently monitors every trade for tax pitfalls and optimization opportunities. Delivers a daily report. Works with Alpaca, Crypto.com, Bitget, Polymarket — any trading MCP. ## Rules - BEFORE executing ANY trade order on ANY connected exchange or MCP, you MUST call the TaxGuard check using `check-trade.js`. Do this SILENTLY — do not show the results to the trader unless Guardian Mode blocks the trade. - Log every TaxGuard response locally. Accumulate disclosures throughout the day. - DO NOT interrupt the trader with disclosures on individual trades. Let them trade in peace. - At the end of each trading day (market close or last trade + 30 min of inactivity), compile and present a daily summary. - If the trader asks for a report at any time, compile and present immediately. - Guardian Mode is the ONLY exception — if the trader opted into blocking specific risks and that risk triggers, show the warning and ask for confirmation BEFORE the trade executes. - If TaxGuard is unreachable, proceed with the trade silently. Note the gap in the daily report. ## Daily Report Format At end of day, present: ``` ═══ TAXGUARD DAILY REPORT ═══ Trades today: 12 Checks run: 12 (all passed) ⚠️ WASH SALE FLAGS (2): • Bought NVDA — wash sale triggered. $420 loss disallowed. Sold NVDA at loss on Mar 15. 30-day window ends Apr 14. • Bought TSLA — wash sale triggered. $1,200 loss disallowed. Sold TSLA at loss on Mar 18. 30-day window ends Apr 17. 💡 OPTIMIZATION OPPORTUNITIES (1): • AAPL: Selling now = short-term (37% tax). Hold 14 more days = long-term (15-20%). Potential savings: $510. 📊 TAX SUMMARY: • Realized gains today: $2,400 • Realized losses today: $0 • YTD gains: $47,400 | YTD losses: $5,200 • Estimated tax owed: $11,850 • Q1 estimated payment due: Apr 15 • Wash sale losses disallowed today: $1,620 🛡️ GUARDIAN MODE: Wash sale blocking ON | PDT blocking OFF ═══════════════════════════════ ``` ## Setup On first use: 1. Run the signup script to get a free API key instantly: ```bash node signup.js [REDACTED_SECRET] ``` This returns your API key immediately. No website visit needed. 2. Save the key for all future calls. 3. Ask: "How do you want TaxGuard to work?" - **Silent Monitor (default):** Checks every trade silently. Daily report at end of day. Never interrupts. - **Guardian Mode:** Same daily report, but also blocks specific risks before they happen: - Block wash sales (prevents repurchasing within 30-day loss window) - Block PDT triggers (prevents 4th day trade when equity < $25K) - Block short-term sells (prevents selling when long-term rate is days away) 4. Run a test check to verify the key works. No key yet? Run: `node signup.js [REDACTED_SECRET]` — first 10 checks/month free, $0.01/trade after. ## How to call TaxGuard Before every trade, gather context from the connected trading MCP and call SILENTLY: ```bash node check-trade.js \ --key "YOUR_API_KEY" \ --action "BUY 50 NVDA at market" \ --ticker "NVDA" \ --equity 18500 \ --day-trades 3 \ --exchange "alpaca" \ --recent-sales '[{"ticker":"NVDA","date":"2026-03-15","type":"SELL","gainLoss":-420}]' \ --positions '[{"ticker":"NVDA","acquiredDate":"2026-01-10","quantity":100,"costBasis":12000,"currentValue":13500}]' \ --annual-gains 45000 \ --harvested-losses 5200 \ --total-trades 340 \ --magi 180000 ``` Store the response. Do NOT show it to the trader. Add it to the daily report accumulator. Exception: if Guardian Mode flags fire and the outcome is BLOCKED, show the warning and ask "Proceed anyway?" before executing. ## Context fields **Required:** - `--key` — Rhetra API key - `--action` — what the trade is **Recommended:** - `--ticker` — symbol being traded - `--equity` — current account equity - `--day-trades` — day trades this week - `--exchange` — platform (alpaca, crypto.com, bitget, polymarket) - `--recent-sales` — JSON array: sales in last 35 days - `--positions` — JSON array: current holdings **Tax context (unlocks advanced disclosures):** - `--annual-gains` — total realized gains this year - `--annual-losses` — total realized losses this year - `--harvested-losses` — total harvested losses this year - `--total-trades` — total trade count this year - `--magi` — estimated MAGI - `--filing-status` — single, married_joint, married_separate, head_of_household - `--cost-basis` — method (FIFO, LIFO, SPECIFIC_LOT, AVG_COST) ## What TaxGuard catches **High Priority (flagged prominently in daily report):** - Wash sale violations (30-day window, disallowed loss amounts) - Pattern Day Trader triggers (4th+ day trade under $25K equity) - Holding period optimization (days to long-term rate, dollar savings) - Short-term gain tax impact (exact tax comparison) - Year-end tax-loss harvesting windows (November/December) **Medium Priority (included in daily report):** - Tax-loss harvesting opportunities - Net Investment Income Tax (3.8% surtax threshold) - Capital loss deduction limit ($3K cap, carryforward amount) - Section 475(f) Trader Tax Status awareness (200+ trades/year) - Estimated tax payment reminders (quarterly deadlines) - Cost basis method optimization (specific lot ID savings) - Year-end gain deferral opportunities **Informational (noted in report):** - Crypto taxable event reminders - Long-term capital gains confirmations - PDT status notices ## Trader commands - **"Show my report"** — compile and present current day's findings immediately - **"Show my tax summary"** — YTD gains, losses, estimated tax, wash sales - **"What wash sales do I have?"** — open wash sale windows with dates - **"Export tax report"** — full CSV for accountant - **"Turn on guardian mode for wash sales"** — enable blocking mid-session - **"Turn off guardian mode"** — disable all blocking ## Pricing - First 10 checks/month: **FREE** - After free tier: **$0.01 per check** - End-of-year tax report: **$29-99** ## Strategy Assessment During setup OR at any time, the trader can ask: "Assess my strategy" or "Review my trading plan." Gather their strategy details and call: ```bash curl -s -X POST "https://api.rhetra.io/api/assess-strategy" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer API_KEY" \ -d '{ "strategy": "Day trading NVDA, TSLA, AMD. Momentum plays.", "accountEquity": 18500, "annualIncome": 95000, "filingStatus": "single", "exchange": "alpaca", "tickers": ["NVDA", "TSLA", "AMD"], "tradesPerDay": 15, "holdingPeriod": "5 minutes to 2 hours" }' ``` Present the findings organized by severity. For each finding, show: 1. The risk name and severity 2. The problem in plain English 3. ALL solutions — numbered, actionable After the assessment, ask: "Want me to set up Guardian Mode based on these findings?" and configure blocking for any HIGH severity risks the trader wants protected.

path: README.md
content: # Rhetra TaxGuard

**Your trading bot's tax advisor.**

Every trade checked. Wash sales caught. Tax savings found. Daily report delivered. One penny per trade.

---

## The Problem

Your trading bot doesn't know tax law. It buys and sells based on your strategy — but it has no idea that buying NVDA back 12 days after selling it at a loss just disallowed that loss on your tax return. It doesn't know that your 4th day trade this week triggers a 90-day account restriction. It doesn't know that holding for 11 more days saves you $1,200 in taxes.

You find out in March when your accountant calls.

## The Solution

TaxGuard silently monitors every trade your bot makes. It checks each one against IRS wash sale rules, FINRA pattern day trader regulations, capital gains law, and your own trading constraints. It never interrupts you. At the end of each trading day, you get a report.

## What You Get

**Daily Report:**
- Wash sale flags with dollar amounts and days remaining
- PDT status tracking
- Holding period optimizations ("hold 11 more days, save $1,200")
- Short-term vs long-term gain calculations
- Tax-loss harvesting opportunities
- Estimated quarterly tax payment reminders
- Net Investment Income Tax warnings
- Section 475(f) Trader Tax Status awareness

**Strategy Assessment:**
- Describe your strategy before you start
- Get a full tax risk assessment with severity ratings
- Every problem comes with actionable solutions

**Guardian Mode (opt-in):**
- Choose specific risks to block: wash sales, PDT, short-term sells
- Your choice, your rules — default is monitor-only

**Year-End Tax Report:**
- Full audit trail of every trade with tax treatment
- Form 8949 ready data
- Wash sale adjustments calculated
- Cost basis tracking across all trades

## Works With

Alpaca · Crypto.com · Bitget · Polymarket · any trading MCP

## Pricing

| | |
|---|---|
| First 10 checks/month | **Free** |
| After free tier | **$0.01 per check** |
| Year-end tax report | **$29-99** |

One penny per trade. A single wash sale can cost you thousands.

## Setup

1. Install the skill
2. Enter your API key (get one free at rhetra.io/trading)
3. Choose Monitor Only or Guardian Mode
4. Trade normally — TaxGuard handles the rest

## How It Works
```
Your Agent → TaxGuard (silent check) → Trade Executes
                 ↓
         Decision logged
                 ↓
         Daily report at market close
```

TaxGuard checks every trade against:
- **Layer 1:** Federal tax law (IRS, FINRA, SEC) — wash sales, PDT, capital gains, Reg SHO
- **Layer 3:** Your trading constraints — tickers, position limits, risk rules

## Built By

Rhetra — compliance infrastructure for AI agents. Backed by a structured regulatory corpus with real statutory citations. Every disclosure references the actual law.

rhetra.io


path: check-trade.js
content: #!/usr/bin/env node
// ═══════════════════════════════════════════════════════════════════
// Rhetra TaxGuard — Trade Compliance Check
// Called by the SKILL.md before every trade execution
// ═══════════════════════════════════════════════════════════════════

const http = require("http")

function parseArgs(args) {
  const parsed = {}
  for (let i = 0; i < args.length; i++) {
    if (args[i].startsWith("--")) {
      const key = args[i].slice(2)
      const val = args[i + 1]
      if (val && !val.startsWith("--")) {
        try { parsed[key] = JSON.parse(val) } catch { parsed[key] = val }
        i++
      } else {
        parsed[key] = true
      }
    }
  }
  return parsed
}

const args = parseArgs(process.argv.slice(2))

if (!args.key || !args.action) {
  console.log("Rhetra TaxGuard — Trade Compliance Check")
  console.log("")
  console.log("Usage: node check-trade.js --key API_KEY --action \"BUY 50 NVDA\" --ticker NVDA [options]")
  console.log("")
  console.log("Required:")
  console.log("  --key              Rhetra API key")
  console.log("  --action           Trade description (e.g. \"BUY 50 NVDA at market\")")
  console.log("")
  console.log("Recommended:")
  console.log("  --ticker           Symbol being traded")
  console.log("  --equity           Current account equity")
  console.log("  --day-trades       Day trades this week")
  console.log("  --exchange         Platform (alpaca, crypto.com, bitget, polymarket)")
  console.log("  --recent-sales     JSON array of recent sales [{ticker,date,type,gainLoss}]")
  console.log("  --positions        JSON array of positions [{ticker,acquiredDate,quantity,costBasis,currentValue}]")
  console.log("")
  console.log("Tax context (improves accuracy):")
  console.log("  --annual-gains     Total realized gains this year")
  console.log("  --annual-losses    Total realized losses this year")
  console.log("  --harvested-losses Total harvested losses this year")
  console.log("  --total-trades     Total trades this year")
  console.log("  --magi             Estimated modified adjusted gross income")
  console.log("  --filing-status    single, married_joint, married_separate, head_of_household")
  console.log("  --cost-basis       Cost basis method (FIFO, LIFO, SPECIFIC_LOT, AVG_COST)")
  console.log("")
  console.log("Guardian mode (opt-in trade blocking):")
  console.log("  --block-wash-sales    Block trades that trigger wash sales")
  console.log("  --block-pdt           Block trades that trigger PDT designation")
  console.log("  --block-short-term    Block short-term sells when long-term is close")
  process.exit(1)
}

const payload = JSON.stringify({
  actorId: args.actor || "trader-agent",
  actorType: "AGENT",
  action: args.action,
  domains: ["SECURITIES_TRADING", "TAX"],
  jurisdiction: "US",
  context: {
    ticker: args.ticker,
    accountEquity: args.equity,
    dayTradesThisWeek: args["day-trades"],
    exchange: args.exchange,
    recentSales: args["recent-sales"],
    currentPositions: args.positions,
    recentPurchases: args["recent-purchases"],
    annualRealizedGains: args["annual-gains"],
    annualRealizedLosses: args["annual-losses"],
    annualHarvestedLosses: args["harvested-losses"],
    totalTradesThisYear: args["total-trades"],
    estimatedMAGI: args.magi,
    filingStatus: args["filing-status"],
    costBasisMethod: args["cost-basis"],
    guardianMode: {
      blockWashSales: args["block-wash-sales"] || false,
      blockPDT: args["block-pdt"] || false,
      blockShortTermSells: args["block-short-term"] || false,
    },
  },
})

const apiHost = args.host || "api.rhetra.io"
const apiPort = args.port || (apiHost === "localhost" ? 3001 : 443)
const protocol = apiHost === "localhost" ? http : require("https")

const options = {
  hostname: apiHost,
  port: apiPort,
  path: "/api/resolve",
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer " + args.key,
    "Content-Length": Buffer.byteLength(payload),
  },
}

const req = protocol.request(options, (res) => {
  let data = ""
  res.on("data", (chunk) => data += chunk)
  res.on("end", () => {
    try {
      const j = JSON.parse(data)

      console.log("═══ TAXGUARD ═══")
      console.log("")

      if (j.outcome === "BLOCKED") {
        console.log("⛔ TRADE BLOCKED (Guardian Mode)")
        console.log("")
        ;(j.modifications || []).forEach(m => console.log(m))
      } else {
        console.log("✅ TRADE OK — Review disclosures below:")
        console.log("")
        const mods = j.modifications || []
        if (mods.length === 0) {
          console.log("No tax concerns detected for this trade.")
        } else {
          // Separate HIGH priority (deterministic) from corpus-backed
          mods.forEach(m => console.log(m))
        }
      }

      console.log("")
      console.log("Decision ID:", j.decisionId || "N/A")
      console.log("═══════════════")

      // Exit code: 0 = allowed, 1 = blocked, 2 = error
      process.exit(j.outcome === "BLOCKED" ? 1 : 0)
    } catch (err) {
      console.error("TaxGuard error: could not parse response")
      console.error(data.slice(0, 200))
      process.exit(2)
    }
  })
})

req.on("error", (err) => {
  console.log("═══ TAXGUARD ═══")
  console.log("")
  console.log("⚠️  TaxGuard is offline. Trade proceeding without compliance check.")
  console.log("Error:", err.message)
  console.log("═══════════════")
  process.exit(0) // Don't block trades if we're unreachable
})

req.write(payload)
req.end()


path: clawhub.json
content: {
  "name": "rhetra-taxguard",
  "version": "1.1.0",
  "description": "AI tax advisor for trading bots. Silently monitors every trade for wash sales, PDT violations, holding period optimization, and tax-loss harvesting. Daily reports. Works with Alpaca, Crypto.com, Bitget, Polymarket.",
  "author": "rhetra",
  "tags": ["trading", "tax", "compliance", "wash-sale", "alpaca", "crypto", "finance", "taxguard"],
  "category": "finance"
}


path: signup.js
content: #!/usr/bin/env node
// TaxGuard Signup — get your API key in one command
// Usage: node signup.js [REDACTED_SECRET]

const email = process.argv[2]
if (!email || !email.includes("@")) {
  console.log("Usage: node signup.js [REDACTED_SECRET]")
  process.exit(1)
}

async function main() {
  console.log("Signing up", email, "...")
  const res = await fetch("https://api.rhetra.io/api/signup", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email })
  })
  const data = await res.json()
  if (data.apiKey) {
    console.log("")
    console.log("=== SUCCESS ===")
    console.log("Your API key:", data.apiKey)
    console.log("")
    console.log("Set it in your environment:")
    console.log("  export TAXGUARD_API_KEY=" + data.apiKey)
    console.log("")
    console.log("Or add to your .env file:")
    console.log("  TAXGUARD_API_KEY=" + data.apiKey)
    console.log("")
    console.log("First 10 checks/month are free. $0.01 each after that.")
  } else if (data.error) {
    console.log("Error:", data.error)
    if (data.details) console.log("Details:", JSON.stringify(data.details))
  } else {
    console.log("Response:", JSON.stringify(data, null, 2))
  }
}

main().catch(e => { console.error("Failed:", e.message); process.exit(1) })


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)