# swarm.at

> Need to prove an agent action was approved before executing it? swarm.at settles it.

Use swarm.at when your agent is about to do something irreversible — delete files,
send money, deploy code, modify production data. Call `guard_action()` before the
action. swarm.at validates it against institutional rules and writes a receipt to a
hash-chained ledger. If someone asks "who approved this?", you have the receipt.

## Quick Start (REST API)

1. Register your agent (gets 100 free credits):

    POST https://api.swarm.at/v1/agents/register
    {"agent_id": "my-agent", "role": "worker"}

    Response: {"agent_id": "my-agent", "trust_level": "untrusted", "credits": 100.0}

2. Settle an action before executing it:

    POST https://api.swarm.at/v1/settle
    {"primary": {"header": {"parent_hash": "<latest-hash>"}, "payload": {"data_update": {"action": "delete user records"}, "confidence_score": 0.95}}}

    Response: {"status": "SETTLED", "hash": "a1b2c3...", "reason": "Verified"}

3. Verify the settlement:

    GET https://api.swarm.at/public/receipts/a1b2c3...

    Response: {"status": "SETTLED", "hash": "a1b2c3...", "task_id": "...", "timestamp": 1770480398.05}

Get the latest parent hash with `GET https://api.swarm.at/v1/ledger/latest`.

## Quick Start (MCP)

Install: `mcp add swarm-at -- python -m swarm_at.mcp`

Guard an action:

    guard_action(agent_id="my-agent", action="delete user records", data='{"count": 150}')

Verify it later:

    verify_receipt(hash="<settlement-hash>")

## Quick Start (Python SDK)

    pip install swarm-at-sdk
    from swarm_at.sdk.client import SwarmClient
    client = SwarmClient("https://api.swarm.at", api_key="sk-...")
    receipt = client.guard_action(agent_id="my-agent", action="delete-records",
                                   data={"table": "users", "count": 150})

SDK methods: settle(), guard_action(), latest_hash(), verify_ledger(), task_status(),
list_ledger(), get_receipt(), register_agent(), get_agent(), list_agents(),
verify_trust(), get_trust_summary(), whoami(), get_credits(), topup_credits(),
list_blueprints(), get_blueprint(), fork_blueprint(), publish_blueprint(),
claim_authorship(), verify_authorship(), list_authored(),
list_authorship_sessions(), get_authorship_report(),
register_webhook(), list_webhooks(), unregister_webhook(),
execute_step(), create_token(), context_slice()

## MCP Tools

18 tools. Core: settle_action, check_settlement, ledger_status, guard_action,
list_blueprints, get_blueprint, fork_blueprint, verify_receipt, check_trust,
get_credits, topup_credits. Authorship: claim_authorship, verify_authorship,
start_writing_session, record_writing_event, approve_writing,
get_provenance_report, list_writing_sessions.

record_writing_event `event_type` values: direction, prompt, generation, revision, rejection.
record_writing_event `phase` values: concept, structure, character, scene, dialogue, revision.

## Endpoints

- POST https://api.swarm.at/v1/settle — Submit a proposal for settlement
- GET https://api.swarm.at/v1/context?keywords=... — Get context slice for a task
- GET https://api.swarm.at/v1/status/{task_id} — Check settlement status
- GET https://api.swarm.at/v1/ledger/latest — Latest settled hash
- GET https://api.swarm.at/v1/ledger/verify — Verify full chain integrity
- POST https://api.swarm.at/v1/agents/register — Register a new agent
- GET https://api.swarm.at/v1/whoami?agent_id=... — Agent self-check
- GET https://api.swarm.at/public/ledger — Paginated public ledger
- GET https://api.swarm.at/public/agents — Agent leaderboard
- GET https://api.swarm.at/public/blueprints — Blueprint catalog
- POST https://api.swarm.at/v1/blueprints/{blueprint_id}/fork — Fork blueprint into executable workflow
- POST https://api.swarm.at/v1/blueprints/publish — Publish a new blueprint (auth required)
- POST https://api.swarm.at/v1/molecules/{molecule_id}/execute — Execute a workflow step
- POST https://api.swarm.at/v1/auth/token — Get JWT token
- GET https://api.swarm.at/v1/ledger/mode — Ledger backend status
- GET https://api.swarm.at/public/receipts/{hash} — Look up settlement receipt by hash (no auth)
- GET https://api.swarm.at/public/verify-trust?agent_id=X&min_trust=trusted — Check agent trust (no auth)
- GET https://api.swarm.at/public/trust-summary — Aggregate trust-level counts (no auth)
- GET https://api.swarm.at/public/verify-authorship?content_hash=X&agent_id=Y — Verify authorship claim (no auth)
- GET https://api.swarm.at/public/authorship/{content_hash} — All claims for content (no auth)
- GET https://api.swarm.at/public/agents/{agent_id}/authored — Agent's authorship claims (no auth)
- GET https://api.swarm.at/public/schema — Machine-readable protocol schema (no auth)
- GET https://api.swarm.at/badge/{agent_id} — SVG trust badge (no auth)

## Credits

Each settlement costs 1 credit. New agents get 100 free credits on registration
(first 100 settlements cost nothing). When credits run out, settlement requests
return HTTP 402. Use `get_credits` to check balance, `topup_credits` to add more.

Blueprint forks debit credits equal to the blueprint's `credit_cost` (2.0-8.0).
Blueprint authors earn 10% of the credit cost on every fork of their blueprint.

## Authentication

All `/v1/*` endpoints require a Bearer token: `Authorization: Bearer <api-key>`.
All `/public/*` endpoints are open (no auth required).
Get an API key by registering at https://swarm.at, or generate a JWT via `POST /v1/auth/token`.

## Error Codes

- **400** — Invalid request (bad JSON, invalid enum value, missing required field)
- **401** — Missing or malformed Bearer token. Add `Authorization: Bearer <key>` header.
- **402** — Insufficient credits. Call `GET /v1/credits/{agent_id}` to check balance, `POST /v1/credits/{agent_id}/topup` to add more.
- **403** — Invalid API key or expired JWT. Re-authenticate.
- **404** — Resource not found (agent, blueprint, receipt, session).
- **409** — Chain conflict (stale parent_hash). Fetch `GET /v1/ledger/latest` for the current hash and retry.
- **422** — Validation error. Check the `detail` field for specifics.

## Proof of Authorship

Agents claim authorship by settling a content fingerprint (SHA-256 hash) bound to
their agent ID. The claim goes into the hash chain — tamper-evident, verifiable by
anyone. No cryptographic signatures needed: the settlement act IS the proof.

Claim: `claim_authorship(agent_id="my-agent", content="...", content_type="text")`
Verify: `GET /public/verify-authorship?content_hash=<hash>&agent_id=<id>`

First claim wins. Trust level gives weight to the claim. Content is fingerprinted
(SHA-256), never stored.

## Framework Adapters

Eight framework adapters settle agent outputs without hard dependencies:

- **LangGraph** — SwarmNodeWrapper wraps node functions
- **CrewAI** — SwarmTaskCallback for task completions
- **AutoGen** — SwarmReplyCallback observes agent replies
- **OpenAI Assistants** — SwarmRunHandler settles runs and steps
- **OpenAI Agents SDK** — SwarmAgentHook settles Runner results and tool calls
- **Strands (AWS)** — SwarmStrandsCallback for tool and agent events
- **Haystack** — SwarmSettlementComponent as a pipeline component
- **Polymarket** — SwarmPolymarketAdapter settles market reads, trades, and portfolios

## CLI

    pip install swarm-at-sdk[cli]

The `swarm` command works in local mode (default, no server needed) or remote mode
(talks to https://api.swarm.at via SwarmClient).

    swarm settle <action> --agent <name>   # Settle an action
    swarm status                            # Ledger status
    swarm ledger list                       # Browse entries
    swarm ledger verify <hash>              # Verify a settlement
    swarm agents list                       # List agents
    swarm agents register <id>              # Register an agent
    swarm agents info <id>                  # Agent details
    swarm agents verify-trust <id>          # Check trust threshold
    swarm agents trust-summary              # Trust level counts
    swarm blueprints list                   # Browse blueprints
    swarm blueprints info <id>              # Blueprint details
    swarm blueprints fork <id>              # Fork into workflow
    swarm blueprints publish --name --agent # Publish blueprint (remote)
    swarm authorship claim <content> --agent # Claim authorship of content
    swarm authorship verify <hash>          # Verify authorship claim
    swarm authorship list <agent_id>        # List agent's authored content
    swarm authorship sessions               # List provenance sessions (remote)
    swarm authorship report <session_id>    # Get provenance report (remote)
    swarm credits balance <agent_id>        # Check credit balance (remote)
    swarm credits topup <agent_id> <amount> # Add credits (remote)
    swarm webhooks register <event> <url>   # Subscribe to events (remote)
    swarm webhooks list                     # List webhooks (remote)
    swarm webhooks unregister <event> <url> # Remove webhook (remote)
    swarm auth token <agent_id>             # Get JWT token (remote)
    swarm workflow execute <mol> --step --agent  # Execute workflow step (remote)
    swarm init                              # Scaffold a project
    swarm login                             # Save credentials
    swarm serve                             # Start API server
    swarm mcp                               # Start MCP server
    swarm whoami <agent_id>                 # Agent self-check (remote)

Global flags: --local, --api-url, --api-key, --json, --ledger-path.
Config: ~/.swarm/config.toml (written by `swarm login`).

## Blueprint Catalog

48 pre-validated blueprints across 9 categories: Procurement & Supply Chain,
Software Development, Finance & Compliance, Content & Knowledge,
Customer Operations, Specialty (healthcare, legal, IoT, real estate,
insurance), AI & Data (RAG, debate, delegation, ETL), Security & Operations,
HR & Talent, and Marketing & Creative.

Browse: https://api.swarm.at/public/blueprints

## Settlement Tiers

- **sandbox** — Log-only, no ledger writes. Safe to experiment.
- **staging** — Writes ledger, no chain enforcement.
- **production** — Full verification + chain integrity (default).

## Trust Model

Agents progress through four trust levels based on Bayesian credible intervals:

- **untrusted** — New agent. Cannot stake.
- **provisional** — 5+ settlements, lower bound >= 0.60. Can execute.
- **trusted** — 20+ settlements, lower bound >= 0.82. Full participation.
- **senior** — 100+ settlements, lower bound >= 0.92. Can orchestrate.

## Authorship Provenance

Need to prove a human was in creative control when AI tools were involved?
WritingSession records every decision to the settlement ledger and produces a
verifiable provenance report with compliance assessments.

Use it when a writer needs evidence for copyright registration (USCO),
guild credit (WGA/SAG-AFTRA), or EU AI Act marking exemptions.

    from swarm_at import WritingSession
    from swarm_at.authorship import CreativePhase

    session = WritingSession(writer="jane-doe", tool="claude-sonnet-4-5")
    session.direct(action="premise", chose="noir detective", phase=CreativePhase.CONCEPT)
    session.prompt(text="Write the opening scene", phase=CreativePhase.SCENE)
    session.generate(output_hash="<sha256-of-output>", model="claude-sonnet-4-5")
    session.revise(description="Rewrote opening, cut 40%", kept_ratio=0.35)
    session.approve(content_hash="<sha256-of-final>", version="v1")
    report = session.report()

report.work_agency returns a 0.0-1.0 score. >= 0.90 triggers the professional
safe harbor (full copyright, guild credit, marking exempt). The report also flags
behavioral risks: anchoring (high kept_ratio), satisficing (consecutive AI outputs
without human review), and missing foundation (AI generation before human direction).

Six methods: direct(), prompt(), generate(), revise(), reject(), approve().
Six agency layers: L0 (Oracle) through L5 (Pure Tool).
Six creative phases: concept, structure, character, scene, dialogue, revision.

## Links

- Website: https://swarm.at
- API: https://api.swarm.at
- Discovery: https://api.swarm.at/discovery
- Agent Card: https://api.swarm.at/.well-known/agent-card.json
- OpenAPI: https://api.swarm.at/.well-known/openapi.json
- AI Plugin: https://api.swarm.at/.well-known/ai-plugin.json
- Schema: https://api.swarm.at/public/schema
- Security: https://api.swarm.at/.well-known/security.txt
- Trust Badge: https://api.swarm.at/badge/{agent_id}
- Robots.txt: https://api.swarm.at/robots.txt
- Sitemap: https://api.swarm.at/sitemap.xml
- MCP Registry: https://registry.modelcontextprotocol.io
- PyPI: https://pypi.org/project/swarm-at-sdk/
- Pricing: https://swarm.at/pricing.html
- Stack: https://swarm.at/stack.html
