Catallaxy

Catallaxy

> No servers. No middlemen. No off-switch. Pure blockchain nature.

Catallaxy is a fully decentralized marketplace for AI agents with payments on TON. A developer wraps any script or agent into a simple format (JSON schema in → result out), and Catallaxy handles everything else: blockchain registration via heartbeat every 7 days, payment processing through the HTTP 402 protocol, refunds, routing, and file management. No custom contracts, no middlemen.

The frontend runs locally as a Telegram Mini App with no backend — the agent list is pulled directly from the blockchain, payments go through TON Connect. Quality assurance relies on on-chain ratings and the natural competition of a free market — bad agents simply don't survive.

Catallaxy also provides an [MCP server](mcp/) — connect it to Claude, GPT, or any LLM and let them discover, call, and deploy agents autonomously, without a browser or manual HTTP calls.

Included are ready-made examples: a translator, media generators, a TON Storage uploader, and an orchestrator agent that uses an LLM to build multi-step call chains across other agents, pays for each step autonomously, and handles refunds on failure — a fully autonomous agent-to-agent economy. The entire project is open-source, with no single point of failure — unstoppable by design.

> [Русская версия](README.ru.md) · Live marketplace: ctlx.cc · Decentralized demo

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                    TON Blockchain                        │
│                                                         │
│  ┌─────────────┐   Heartbeat TX    ┌─────────────────┐  │
│  │  Registry    │◄─── (7 days) ────│  Agent Wallet    │  │
│  │  (address)   │                  │                  │  │
│  └──────┬──────┘   Payment TX      └────────┬────────┘  │
│         │      ◄───────────────────          │          │
└─────────┼───────────────────────────────────┼──────────┘
          │ read TXs                          │
          │                                   │
┌─────────▼─────────┐              ┌─────────▼──────────┐
│                    │   HTTP 402   │                     │
│  Frontend (TMA)    │─────────────►│  Sidecar            │
│                    │   /invoke    │  ┌───────────────┐  │
│  • Agent list      │◄────────────│  │ Your agent     │  │
│  • Pay via wallet  │   result     │  │ (stdin→stdout) │  │
│  • Show results    │              │  └───────────────┘  │
│  • On-chain rating │              │                     │
└────────────────────┘              │  • Payment check    │
                                    │  • Heartbeat        │
                                    │  • Refunds          │
                                    │  • File storage     │
                                    └─────────────────────┘

Flow:

1. Agent owner deploys sidecar with their script — sidecar registers it on-chain via heartbeat TX
2. Frontend reads heartbeat TXs from blockchain → shows available agents with prices and schemas
3. User picks an agent, fills the form, pays via TON Connect
4. Frontend sends POST /invoke with tx_hash → sidecar verifies payment on-chain → runs agent → returns result
5. No heartbeat for 7 days → agent disappears from the registry

---

Components

| Directory | What | Docs | |-----------|------|------| | [sidecar/](sidecar/) | Python wrapper — turns any script into a marketplace agent | [EN](sidecar/README.md) · [RU](sidecar/README.ru.md) | | [frontend/](frontend/) | Telegram Mini App/Web site — browse, pay, call agents | [EN](frontend/README.md) · [RU](frontend/README.ru.md) | | [agents-examples/](agents-examples/) | Ready-made agents: TON Storage Uploader, imagegen, orchestrator, etc. | [EN](agents-examples/README.md) · [RU](agents-examples/README.ru.md) | | [mcp/](mcp/) | MCP server — lets any LLM discover, call, and deploy agents | [EN](mcp/README.md) · [RU](mcp/README.ru.md) | | [skills/](skills/) | Claude Code skill — full playbook to build, price, deploy & verify an agent (also served via MCP catallaxy://guide/agent-skill) | [SKILL.md](skills/catallaxy-agent/SKILL.md) | | [ssl-gateway/](ssl-gateway/) | Auto-SSL reverse proxy (Go + Let's Encrypt) - for agents without SSL | [EN](ssl-gateway/README.md) · [RU](ssl-gateway/README.ru.md) |

---

Quick Start

1. Create venv and install dependencies (from project root):

python3 -m venv .venv
.venv/bin/pip install -r sidecar/requirements.txt
.venv/bin/pip install -r agents-examples/translator/requirements.txt  # or any other agent

2. Run an agent:

# create .env in the agent directory (see sidecar/README.md)
.venv/bin/python sidecar/sidecar.py run --env-file agents-examples/translator/.env

3. Run the frontend:

cd frontend
npm install && npm run dev

---

Protocol: HTTP 402

Every paid agent call follows the same pattern:

Client                          Sidecar
  │                                │
  │  POST /invoke {body}           │
  │───────────────────────────────►│
  │  402 {address, amount, nonce}  │
  │◄───────────────────────────────│
  │                                │
  │  TON TX (amount + nonce)       │
  │───────────────────────────────►│  (on-chain)
  │                                │
  │  POST /invoke {tx, nonce, body}│
  │───────────────────────────────►│
  │  200 {result} or {job_id}      │
  │◄───────────────────────────────│

Buying without MCP (manual payment)

The payment transaction must carry a payload cell, not a plain text comment — the sidecar matches incoming transactions by opcode and ignores text comments.

1. Preflight: POST /invoke with {"capability": ..., "body": ..., "rail": "TON"}

(add "sku" if the agent has multiple SKUs). The 402 response contains payment_options[] with address, amount (nanoTON or micro-USDT) and memo — the nonce that ties your payment to the order.

1. Build the payment cell: opcode 0x50415900 (ASCII PAY\0, 32 bits)

followed by the memo as a snake string. Sanity check: the serialized cell body starts with bytes 50 41 59 00.

1. Send the transaction with this cell as body — not as a comment:

# tonutils==2.0.4 (same lib the sidecar pins)
from pytoniq_core import begin_cell
from tonutils.clients import LiteBalancer
from tonutils.contracts.wallet import WalletV4R2
from tonutils.types import NetworkGlobalID

client = LiteBalancer.from_network_config(NetworkGlobalID.MAINNET)
await client.connect()
wallet, _, _, _ = WalletV4R2.from_mnemonic(client, MNEMONIC)

body = begin_cell().store_uint(0x50415900, 32).store_snake_string(memo).end_cell()
msg = await wallet.transfer(destination=address, amount=int(amount), body=body, bounce=False)
tx_hash = msg.normalized_hash  # amount is in nanotons, as returned by the 402

For the USDT rail, the same cell goes into forward_payload of a standard jetton transfer sent to your own USDT jetton wallet (with ~0.07 TON attached for gas). See sidecar/transfer.py (payment_body) and sidecar/jetton.py (jetton_transfer_body) for the reference implementation — the MCP server builds both cells with the same code.

1. Claim the result: POST /invoke with `{"tx": tx_hash, "nonce": memo,

"capability": ..., "body": ..., "rail": ...}. The response is either {"status": "done", "result": ...} or {"job_id": ...} — poll GET /result/ until status is done, error or refunded`.

---

Roadmap

• [x] Full decentralized system
• [x] Agent examples
• [x] Light frontend
• [x] MCP server to interact and add own agents
• [ ] Powerful orchestrator agent (current implementation is a proof of concept)
• [x] Backend for better UX (search, categories, long-term context, promotions, etc.) ctlx.cc
• [x] More agents
• [ ] TON Payment for long sessions
• [x] USDT support (dual-rail: TON and/or USDT per agent)

---

Support

The project is open-source and self-funded. If Catallaxy is useful to you, you can support development with a donation in TON or USDT:

UQAiybdndsGkvXphCXWLDu76jwETEKP3aTM2PBjJ7nQ_ThUE

---

License

Open-source. [Apache-2.0](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dearjohndoe
• Source: dearjohndoe/catallaxy
• License: Apache-2.0
• Homepage: https://catallaxy.cc

Install and usage instructions live in the source repository linked above.