The API layer, agent session management, event system, and monitoring infrastructure for the Execrow protocol.
This repository contains the backend service that powers the Execrow operator dashboard, developer API, agent session coordination, and real-time event streaming. It is the operational layer that sits between the on-chain contracts and the human-facing interfaces.
- Overview
- Architecture
- API Reference
- Repository Structure
- Prerequisites
- Getting Started
- Environment Variables
- Development
- Testing
- Contributing
- License
The Execrow backend provides:
- REST API — for operator dashboard and external integrations
- WebSocket API — real-time event streaming for task state changes, payment events, and agent activity
- Agent Session Manager — tracks active agent sessions, their current tasks, and wallet states
- Stellar Indexer — indexes Execrow-related on-chain events into a queryable database
- Notification Service — alerts operators about important events (task completions, disputes opened, budget thresholds reached)
- Analytics Engine — aggregates protocol usage data for the operator dashboard
┌──────────────────────────────────────────────────────┐
│ Execrow Backend │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ REST API │ │ WebSocket │ │
│ │ │ │ API │ │
│ └──────────────┘ └──────────────┘ │
│ │ │ │
│ └────────┬──────────┘ │
│ │ │
│ ┌────────▼──────────┐ │
│ │ Core Services │ │
│ │ │ │
│ ┌──────┴──────┐ ┌─────────┴──────┐ │
│ │ Session │ │ Stellar │ │
│ │ Manager │ │ Indexer │ │
│ └─────────────┘ └────────────────┘ │
│ │
│ ┌─────────────┐ ┌────────────────┐ │
│ │Notification │ │ Analytics │ │
│ │ Service │ │ Engine │ │
│ └─────────────┘ └────────────────┘ │
│ │
└──────────────────────┬───────────────────────────────┘
│
┌────────▼────────┐
│ PostgreSQL │
└─────────────────┘
Full API documentation will be available at docs/api-reference.md. Key endpoint groups:
| Group | Base Path | Description |
|---|---|---|
| Agents | /api/v1/agents |
Create, manage, and monitor agents |
| Tasks | /api/v1/tasks |
Task lifecycle and history |
| Escrow | /api/v1/escrow |
Escrow creation and status |
| Reputation | /api/v1/reputation |
Agent reputation scores |
| Disputes | /api/v1/disputes |
Dispute management |
| Analytics | /api/v1/analytics |
Usage and performance metrics |
| Webhooks | /api/v1/webhooks |
Register webhook endpoints |
execrow-backend/
├── src/
│ ├── index.ts
│ ├── api/
│ │ ├── routes/
│ │ │ ├── agents.ts
│ │ │ ├── tasks.ts
│ │ │ ├── escrow.ts
│ │ │ ├── reputation.ts
│ │ │ ├── disputes.ts
│ │ │ ├── analytics.ts
│ │ │ └── webhooks.ts
│ │ ├── middleware/
│ │ │ ├── auth.ts
│ │ │ ├── rateLimit.ts
│ │ │ └── validation.ts
│ │ └── websocket/
│ │ ├── server.ts
│ │ └── events.ts
│ ├── services/
│ │ ├── sessionManager.ts
│ │ ├── stellarIndexer.ts
│ │ ├── notificationService.ts
│ │ └── analyticsEngine.ts
│ ├── db/
│ │ ├── schema.ts
│ │ ├── migrations/
│ │ └── queries/
│ ├── stellar/
│ │ ├── client.ts
│ │ ├── contractClient.ts
│ │ └── eventParser.ts
│ └── types/
│ └── index.ts
├── tests/
│ ├── api/
│ ├── services/
│ └── integration/
├── docker/
│ ├── Dockerfile
│ └── docker-compose.yml
├── .env.example
├── package.json
├── tsconfig.json
├── .gitignore
├── CONTRIBUTING.md
├── LICENSE
└── README.md
- Node.js
>=20.0.0 - PostgreSQL
>=15 - Docker (recommended for local development)
git clone https://github.com/Execrow/execrow-backend.git
cd execrow-backend
cp .env.example .env
npm install
docker-compose up -d postgres
npm run migrate
npm run devDATABASE_URL=postgresql://localhost:5432/execrow
STELLAR_NETWORK=testnet
STELLAR_RPC_URL=https://soroban-testnet.stellar.org
AGENT_REGISTRY_CONTRACT_ID=
ESCROW_ENGINE_CONTRACT_ID=
REPUTATION_LEDGER_CONTRACT_ID=
JWT_SECRET=
PORT=3000Browse good first issue to get started. Read CONTRIBUTING.md before opening a pull request.
Apache 2.0 — Execrow Organization, 2025
Part of the Execrow open-source organization.
The payment infrastructure layer for autonomous AI agents.