# Ayni — The Agent Economy on Lightning

> Marketplace where AI agents pay tribes of human contributors via Lightning Network for specialized knowledge. Every payment splits, in seconds and at near-zero cost, across all of the tribu's contributors. Built on L402 + MoneyDevKit + Bitcoin mainnet.

If you are an AI agent or an LLM coding assistant integrating with Ayni, this single document tells you everything you need to call the API and pay for a query autonomously. For a richer machine-readable description, also fetch `https://ayniw.com/.well-known/agent-skill.json`.

## What an agent does, end to end

```
1. GET https://ayniw.com/api/ayni/<plugin>?q=<your query>
   → HTTP 402 Payment Required
     body:    { "invoice": "lnbc...", "macaroon": "...", "paymentHash": "...", "amountSats": N, "expiresAt": ... }
     header:  WWW-Authenticate: L402 macaroon="..." invoice="lnbc..."

2. Pay the Lightning invoice with your wallet.
   The Lightning network returns a preimage on success.

3. Retry the same GET with:
     Authorization: L402 <macaroon>:<preimage>
   → HTTP 200 OK
     body: { "tribu": {...}, "query": "...", "answer": "...", "ayni": { "paid": N, "currency": "SAT", "splits": [...] } }
```

The server verifies `sha256(preimage) === paymentHash` before unlocking. Macaroons are HMAC-signed with the merchant's access token, so tampering is detected and rejected.

## Recommended wallet for autonomous agents

The simplest way to make an LLM coding assistant (Claude Code, Codex, Cursor, etc.) pay for an Ayni call without human input:

```bash
# 1. Install and initialise once
npx @moneydevkit/agent-wallet@latest init

# 2. Start the daemon
npx @moneydevkit/agent-wallet@latest start --daemon

# 3. Receive an invoice to fund (any wallet pays it)
npx @moneydevkit/agent-wallet@latest receive 200

# 4. Pay an L402 invoice (returns the preimage)
npx @moneydevkit/agent-wallet@latest send "lnbc1u1p..."
# → {"payment_id":"...","payment_hash":"...","status":"completed","preimage":"..."}
```

The wallet also accepts BOLT12 offers and Lightning Addresses (`name@domain`).

Other wallets confirmed compatible: Phoenix, Alby, Strike, Wallet of Satoshi, and any L402-compliant client.

## Available tribes

- **Tax PE** (`tributario-pe`) — 100 sat/call · 5 contributors · Legal & Finance
  https://ayniw.com/api/ayni/tributario-pe?q=YOUR_QUERY
  Experts in Peruvian tax law: VAT (IGV), Income Tax, SUNAT, RUC.
  Split per call: 40 sat → Lead curator, 30 sat → Legal validator, 10 sat → Contributor, 10 sat → Contributor, 10 sat → Contributor

- **Data Science ES** (`data-science-es`) — 75 sat/call · 3 contributors · Technology
  https://ayniw.com/api/ayni/data-science-es?q=YOUR_QUERY
  ML, Python, statistics, and data analysis for the Spanish-speaking market.
  Split per call: 39 sat → Lead curator, 18 sat → Python Expert, 18 sat → Statistician

- **Legal MX** (`legal-mx`) — 150 sat/call · 4 contributors · Legal & Finance
  https://ayniw.com/api/ayni/legal-mx?q=YOUR_QUERY
  Mexican corporate and tax law. SAT, IMSS, contracts, SAS.
  Split per call: 54 sat → Lead curator, 37 sat → Corporate, 37 sat → Tax, 22 sat → Labor

- **HealthTech BO** (`healthtech-bo`) — 200 sat/call · 6 contributors · Healthcare
  https://ayniw.com/api/ayni/healthtech-bo?q=YOUR_QUERY
  Bolivian medical protocols, generic medications, and clinical guidelines.
  Split per call: 60 sat → Lead physician curator, 40 sat → Pharmacist, 30 sat → Nursing, 30 sat → Contributing physician, 20 sat → Public health, 20 sat → Researcher

- **DeFi AR** (`defi-ar`) — 125 sat/call · 4 contributors · Crypto & DeFi
  https://ayniw.com/api/ayni/defi-ar?q=YOUR_QUERY
  DeFi, crypto, and digital asset taxes in Argentina. AFIP, CEDEARs.
  Split per call: 45 sat → DeFi expert, 37 sat → Tax advisor, 25 sat → Crypto analyst, 18 sat → Contributor

- **EduTech CO** (`edutech-co`) — 80 sat/call · 3 contributors · Education
  https://ayniw.com/api/ayni/edutech-co?q=YOUR_QUERY
  Colombian pedagogical methodologies, MEN curriculum, and educational gamification.
  Split per call: 36 sat → Pedagogue, 24 sat → Curriculum designer, 20 sat → EdTech specialist

## How redistribution works (the unique part)

Every payment is split, on Lightning, across the tribe's contributors per the percentage shares each earned. Splitting one payment across N humans for fractions of a cent is **economically impossible** with cards or Stripe (per-tx fees exceed each recipient's amount); Lightning makes it trivial. This is reciprocity (*ayni*) implemented in code.

For the demo we use a naive splitter that issues one Lightning send per contributor sequentially (see [`scripts/demo-flow.sh`](https://github.com/d3nn1sVZ/Ayni-agents/blob/main/scripts/demo-flow.sh) in the source). Future revisions will switch to native multi-recipient primitives (Spark / atomic multi-path).

## Why Lightning, not Stripe or stablecoins

- **Stripe / cards:** ~$0.30 minimum fee per transaction → splitting 100 sat across 5 contributors is mathematically negative-sum.
- **Stablecoins (x402, USDC):** non-trivial gas + per-transfer fees on most chains, plus a single corporate gatekeeper (issuer) who sets policy and can freeze funds.
- **Ayni on Lightning:** ~$0.00 fee → distributing 100 sats across 5 contributors costs effectively nothing and settles in seconds, 24/7, across borders, no contracts, no KYC, no subscriptions.

## Resources for deeper integration

- **Machine-readable manifest:** https://ayniw.com/.well-known/agent-skill.json
- **L402 protocol spec:** https://docs.lightning.engineering/the-lightning-network/l402
- **MoneyDevKit docs:** https://docs.moneydevkit.com
- **Source code:** https://github.com/d3nn1sVZ/Ayni-agents
- **Live dashboard:** https://ayniw.com/
- **L402 directory:** https://402index.io (we are domain-verified there)

## Contact for partners and contributors

- Maintainer: Ayni team — Hack Nation 5 / Spiral Challenge 02
- Email: x@dennisvivas.com

---

This document follows the [llms.txt](https://llmstxt.org) convention. Last regenerated automatically from the live tribu manifest.