Ailabra Agent Profit Ledger

<!-- mcp-name: io.github.jsjfin/ailabra-agent-profit-ledger -->

Live product · API docs · Synthetic report · OpenAPI

Know whether your autonomous agent actually made money.

Wallet balance is not profit. Ailabra Agent Profit Ledger attributes revenue and costs to agents, ventures, and experiments, then returns deterministic P&L, cash flow, evidence coverage, and signed operational reports. “ProfitOS” is an internal codename only; public branding is environment-configurable.

Complete executable examples are available at /api/v1/examples. The OpenAPI contract documents all HTTP operations, schemas, capability scopes, x402 prices, retention, quotas, idempotency, and error responses.

This is not a wallet, custodian, payment facilitator, trading system, tax product, statutory accounting system, audit, or financial, investment, legal, or tax advice.

What works

• Exact decimal calculation with versioned formulas; no LLM decides profit.
• Revenue, refunds, expenses, fees, transfers, capital, withdrawals, assets, and explicit adjustments.
• Separate currency totals or caller-supplied, timestamped exchange rates—USDC is never relabelled USD.
• Paid x402 v2 calculate (0.01 USDC), analyze (0.05 USDC), attest (0.25 USDC), and workspace (0.25 USDC) operations.
• Capability-scoped workspaces with hashed one-time tokens, quotas, expiration, export, and deletion.
• Ed25519 reports with SHA-256 result hashes and honest evidence statements.
• Streamable HTTP MCP at https://x402.ailabra.org/mcp, OpenAPI 3.1, SDK, CLI, Bazaar metadata, and agent discovery files.
• Base Sepolia through x402.org and Base mainnet native USDC through Coinbase CDP.

Architecture

HTTP / MCP client
    │
    ├── free discovery, schemas, docs, verification
    ├── x402 v2 middleware ── CDP/x402.org facilitator ── Base USDC
    │                              │
    │                         payment audit
    └── deterministic engine ── SQLite WAL
             │                    ├── workspaces/events/quotas
             └── Ed25519 signer   └── reports/audit/analytics

The seller needs only a public receive address. Never supply a seller private key, Phantom recovery phrase, or seed phrase. See ARCHITECTURE.md, CALCULATION_RULES.md, and EVENT_SCHEMA.md.

Local development

Requires Node.js 20+; CI and the container use current Node 22/24 runtimes.

npm ci
cp .env.example .env
npx tsx scripts/generate-signing-key.ts secrets/report-signing-key.pem
npm run dev
npm run format:check && npm run lint && npm run typecheck && npm test && npm run build

Use Base Sepolia and a separate funded buyer wallet for development. BUYER_PRIVATE_KEY must be an ignored local EVM key (0x plus 64 hex characters), never the seller key.

HTTP and x402

curl -i -X POST https://x402.ailabra.org/api/v1/x402/profit/calculate \
  -H 'content-type: application/json' \
  --data @samples/synthetic-events.json

The initial response is HTTP 402. A compatible x402 buyer signs and retries. The included client does that:

npm run buyer -- https://x402.ailabra.org/api/v1/x402/profit/calculate samples/synthetic-events.json

Stateless raw events are not retained. Payment audit metadata and, for attestations, the signed report are retained. Full protocol details are in X402.md.

SDK and CLI

The package is deliberately private until the npm name and publishing account are authorized. Build locally, then:

npm run build
node dist/cli.js calculate samples/synthetic-events.json --dry-run --json
node dist/cli.js calculate samples/synthetic-events.json --base-currency USDC
node dist/cli.js workspace create

Paid commands load BUYER_PRIVATE_KEY only from the environment. Workspace commands use AGENTPROFIT_WORKSPACE_ID, AGENTPROFIT_WRITE_TOKEN, or AGENTPROFIT_READ_TOKEN. --output, --dry-run, --json, --base-currency, and --no-retain are supported.

TypeScript:

import { AgentProfitClient } from "ailabra-x402-seller";
const client = new AgentProfitClient({
  buyerPrivateKey: process.env.BUYER_PRIVATE_KEY as `0x${string}`,
});
const { body } = await client.calculate({ events });

Python and generic agents can use the OpenAPI schema and any x402 v2 client. Codex/Claude Code MCP clients should configure { "type": "streamable-http", "url": "https://x402.ailabra.org/mcp" }. See MCP.md.

Workspace flow

1. Pay POST /api/v1/x402/workspaces.
2. Securely store the admin, write, and read tokens returned once. Only SHA-256 token hashes are stored.
3. Ingest events at /api/v1/workspaces/{id}/events or /events/batch with the write token.
4. Read profit, cash flow, agents, ventures, experiments, data quality, or export with the read token.
5. Generate reports or delete with the admin token.

Unknown or unauthorized workspaces always return 404 to avoid exposing existence.

MCP

The remote server exposes paid profit_calculate, profit_analyze, profit_attest, and workspace_create tools using the official x402 MCP wrapper. Authenticated workspace and free report-verification tools are also available. Metadata states price, retention, signing, and evidence limitations. The prepared official registry definition is server.json.

Deployment

docker compose build
docker compose up -d
docker compose ps
curl http://127.0.0.1:8899/health

Compose binds only 127.0.0.1:8899, runs as non-root with a read-only filesystem and dropped capabilities, mounts the signing key as a read-only secret, persists SQLite, rotates logs, health-checks, and restarts automatically. Cloudflare is assumed to route x402.ailabra.org to http://localhost:8899. See DEPLOYMENT.md and OPERATIONS.md.

Documentation

• CALCULATION_RULES.md — deterministic treatment and formulas
• EVENT_SCHEMA.md — schema, idempotency, currencies, evidence
• SECURITY.md and PRIVACY.md
• MCP.md, X402.md, and DISCOVERY.md
• marketing/CASE_STUDY.md — transparent synthetic case study
• VERIFICATION.md — payment/deployment evidence

Current limitations

Single-server SQLite, one configured Base network at a time, no arbitrary wallet sync, no automatic historical FX, no depreciation engine, no refunds automation, and no statutory accounting/tax workflow. Receipt imports are receipt_supplied unless a configured trusted RPC verifies the official transfer. Solana can be added at the existing network/scheme boundary after end-to-end facilitator testing.

Official references: x402 seller quickstart, CDP Bazaar, MCP remote publishing, and Circle USDC addresses.