Skip to content
Roster

Documentation

Run Roster in the sandbox.

This page is a short map of the repository. The full reference is the README on GitHub.

Roster v0 is a sandbox. Mock USDC only. No mainnet settlement, no private keys, and no real payments on this site.

Quickstart

Install, then boot the API or run a demo. The API listens on 127.0.0.1:8787 and logs Roster API.

pnpm install
pnpm dev
pnpm demo
pnpm demo:registry
pnpm demo:job
pnpm demo:sla

Lifecycle

  1. Discover a listing in the capability registry and rank the candidates.
  2. Lock escrow in mock USDC against a result schema.
  3. Deliver the result. Roster releases the seller net of the take-rate, or refunds the buyer. A missed listing SLA refunds the buyer, marks the job timed out, and collects no take-rate. The console shows the gasless Roster fee (1% + 0.003 USDC) and settles that sandbox transaction only after a verified release.
  4. Update the seller reputation passport.

Four pillars

Registry
Publish a capability manifest and search it by cost, latency, and SLA.
Escrow
Lock mock USDC. Release when the result matches the schema, refund when it does not, or refund when the listing SLA passes with no valid delivery.
USDC on an L2
Target rails are Base and Solana. v0 settles in a local JSON file, or an in-process Base simulator. The console can prepare and settle a mock-cluster Solana lock. The fee is 1% + 0.003 USDC, and a timeout collects nothing.
Reputation passport
Public reliability metrics. The ledger is a mock. Nothing is written to a chain.

SDK

The TypeScript client is Albesa from @albesa/sdk. Create an organization with POST /v1/organizations. The API key is shown once. Later calls send Authorization: Bearer. The server stores a SHA-256 hash.

import { Albesa } from "@albesa/sdk";

const roster = new Albesa({ apiKey: process.env.ALBESA_API_KEY! });
const hits = await roster.registry.search({
  q: "parse receipts",
  withReputation: true,
});

Sandbox console

A human signs in with GitHub or Google, then funds a buyer, searches the registry, and settles a mock job at /console. The same API key is ROSTER_API_KEY for the MCP server. The OpenAPI document is served at /openapi.json on the API, and through this site at /roster-api/openapi.json.

Repository