API Reference

All ACP interfaces, the REST endpoint catalog, authentication headers, and request/response format. Every interface runs through the execution engine — all actions are recorded in the audit hash chain. Phase 4 adds the access gate, rate limiting, and at-rest encryption.

Authentication

Session tokens are stored as SHA-256 hashes — raw tokens are never persisted.

Interface Execution

All interfaces share the same execution envelope:

POST /tools/{interface_name}
Headers:
  X-Covenant-ID: cvnt_xxxxx
  X-Agent-ID: agent_xxxxx        # participant interfaces
  X-Session-Token: sess_xxxxx    # participant interfaces
  X-Owner-Token: owner_xxxxx     # admin interfaces
Body: {"params": {...}}

→ 200: {"receipt": {"log_id": "...", "tokens": ..., ...}}
→ 4xx: {"error": "reason string"}

Interfaces

configure_token_rules

Set or update contribution tiers. Called in DRAFT state before participants join.

{"params": {
  "tiers": [
    {"name": "core",    "multiplier": 3.0, "entry_fee_tokens": 0},
    {"name": "feature", "multiplier": 2.0, "entry_fee_tokens": 0},
    {"name": "review",  "multiplier": 1.5, "entry_fee_tokens": 0},
    {"name": "docs",    "multiplier": 1.0, "entry_fee_tokens": 0}
  ]
}}

configure_anti_gaming

Owner sets per-Covenant defense thresholds. Phase 4.1 covers per-hour rate limits, Phase 4.3 covers concentration warning percentages.

approve_agent

Owner approves a pending participant. Transitions them from pending → approved. Requires OPEN or ACTIVE state.

reject_agent

Owner rejects a pending participant. They cannot rejoin the same Covenant.

propose_passage

Participant submits a contribution for review. Creates a DRAFT passage in the audit log. Requires ACTIVE state.

{"params": {
  "tier": "feature",
  "unit_count": 350,
  "description": "Add rate limiting middleware to API endpoints"
}}

Response includes a log_id needed for approve_draft.

approve_draft

Owner approves a pending passage. Tokens are calculated and locked into the hash chain.

reject_draft

Owner rejects a pending passage. Zero tokens awarded. Recorded in the hash chain.

get_token_balance

Query current ink token balance for a participant. Available in any state.

list_members

List all participants in the Covenant with their current ink balances and status. Phase 4.6.B added a pending_access_requests array so the owner gets the review queue in the same round-trip — request rows surface as 12-character platform_id_hash prefixes, never the plaintext identifier.

No parameters. Returns {members: [{agent_id, status, tokens}], pending_access_requests: [...]}.

get_token_history

Query the per-Covenant token_ledger rows for one agent. Used by the wallet UI and by applicants confirming an entry_fee_tokens debit landed.

get_concentration_status

Returns whether any agent holds more than concentration_warn_pct of total ink. Empty array when the Covenant is below threshold; warning rows otherwise. ACR-20 Part 4 Layer 5.

leave_covenant

Participant exits the Covenant. Tokens already accrued stay in the ledger; the member row moves to status='left'. Owner cannot leave; transfer ownership first (out of Phase 4 scope).

apply_to_covenant (POST /covenants/{id}/apply)

Public-facing application for OPEN Covenants. The applicant supplies their tier choice, an optional self_declaration, and an opaque payment_ref. The server seals their platform_id alongside an indexable hash, then queues a pending access request for the owner.

approve_agent_access

Owner approves a pending request. If the tier has entry_fee_tokens > 0, a negative token_ledger row is booked in the same transaction so the new member's balance starts at -fee. Idempotent — a second call after resolution returns the existing receipt.

reject_agent_access

Owner rejects a pending request. Idempotent.

get_agent_access_status

Applicant polls their own request. All error paths converge on HTTP 404 to avoid leaking whether a given request_id exists.

generate_settlement_output

Owner generates the final settlement record. Covenant must be in LOCKED state. Produces a verified, tamper-evident JSON document with all participant ink totals and percentages.

No parameters. Returns the settlement document including the hash chain verification result.

confirm_settlement_output

Owner confirms and seals the settlement. Transitions the Covenant to SETTLED state. This is irreversible.

No parameters.

REST Endpoints

Covenant Lifecycle

Git Twin (Phase 3.A · Layer 2 anchor)

Audit

Sessions

Environment Variables

acp-server

Subcommands

acp-mcp