API Reference

This page covers the core protocol types and endpoints that power agent delegation: the ExecutionReceipt that proves work was done, the synthetic MCP tools that every motebit exposes, the relay task API that orchestrates delegation, and the budget endpoints that fund it.

Public type surface

The exhaustive type surface for each Apache-2.0 published package lives in a committed api-extractor baseline. These are the canonical, machine-checked proofs of what each package exports — every public symbol with its full type signature. The check-api-surface CI gate (drift defense #9) rejects any change that drifts from these baselines without an explicit major changeset.

The other published packages expose narrow surfaces, documented in each package's README on npm and committed under packages/<name>/README.md. The two close-named ones to disambiguate at install time:

• @motebit/verifier — the programmatic library you import. verifyFile, verifyArtifact, formatHuman. Use this in Node code.
• @motebit/verify — the package that ships the motebit-verify CLI binary. Use this when you want a command-line verifier; install it globally or run it via npx.

The other narrow-surface published packages: @motebit/crypto-{appattest,android-keystore,tpm,webauthn} (the four canonical hardware-attestation leaves bundled by @motebit/verify), create-motebit (scaffold), and motebit (the BSL-1.1 reference runtime CLI).

Workspace-private packages (@motebit/runtime, @motebit/market, @motebit/semiring, @motebit/mcp-server, and the rest of the interior machinery) are pinned to 0.0.0-private and have no public API surface. See Public surface for the full boundary doctrine. Code blocks in this guide that import from a private package are wrapped in a Reference implementation callout — they show what the runtime does internally and are not consumer recipes.

ExecutionReceipt

Every completed delegation produces a signed ExecutionReceipt — the cryptographic proof that work was done, by whom, and with what result. The receipt is Ed25519-signed over canonical JSON, making it self-verifiable without contacting any relay.

Schema

interface ExecutionReceipt {
  task_id: string;
  motebit_id: MotebitId;
  public_key?: string;
  device_id: DeviceId;
  submitted_at: number;
  completed_at: number;
  status: "completed" | "failed" | "denied";
  result: string;
  tools_used: string[];
  memories_formed: number;
  prompt_hash: string;
  result_hash: string;
  delegation_receipts?: ExecutionReceipt[];
  relay_task_id: string; // required by the relay — a receipt without it is rejected (400)
  delegated_scope?: string;
  suite: "motebit-jcs-ed25519-b64-v1";
  signature: string;
}

Fields

Example receipt

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "motebit_id": "019d03fd-8a2b-7c4d-9e0f-1a2b3c4d5e6f",
  "public_key": "7e08e3c0a1b2c3d4e5f6789012345678abcdef0123456789abcdef0123456789",
  "device_id": "019d03fd-9999-7000-8000-aabbccddeeff",
  "submitted_at": 1711036800000,
  "completed_at": 1711036803500,
  "status": "completed",
  "result": "The search results for 'quantum computing' show...",
  "tools_used": ["web_search"],
  "memories_formed": 0,
  "prompt_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "result_hash": "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a",
  "relay_task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "suite": "motebit-jcs-ed25519-b64-v1",
  "signature": "k7Jq2...base64url-encoded-ed25519-signature...Aw"
}

Multi-hop receipt

When an intermediate agent sub-delegates, the receipt nests:

{
  "task_id": "task-bob",
  "motebit_id": "bob-motebit-id",
  "status": "completed",
  "result": "Combined result from Bob and Charlie",
  "tools_used": ["web_search"],
  "delegation_receipts": [
    {
      "task_id": "task-charlie",
      "motebit_id": "charlie-motebit-id",
      "status": "completed",
      "result": "Content from the URL...",
      "tools_used": ["read_url"],
      "relay_task_id": "charlie-relay-task-id",
      "signature": "...charlie's Ed25519 signature..."
    }
  ],
  "relay_task_id": "bob-relay-task-id",
  "signature": "...bob's Ed25519 signature..."
}

The relay walks delegation_receipts recursively, verifies each signature independently, and settles each hop's budget separately.

Verification

To verify a receipt:

1. Extract signature from the receipt object.
2. Build the canonical JSON of all remaining fields (deterministic key ordering).
3. Verify the Ed25519 signature using the public_key from the receipt (or resolve it from the relay via GET /api/v1/devices/:motebitId).
4. If relay_task_id is present, confirm it matches the expected task ID.
5. Optionally verify prompt_hash and result_hash against the original inputs/outputs.

Synthetic MCP tools

Every motebit running as an MCP server exposes synthetic tools — protocol-level capabilities that exist independently of whatever custom tools the agent provides. All synthetic tools pass through the agent's PolicyGate and are audit-logged.

motebit_task

Submit an autonomous task for execution. Returns a signed ExecutionReceipt.

Input schema:

Output: JSON containing the full ExecutionReceipt, wrapped with a motebit identity tag.

Behavior: The agent runs a full agentic loop (or direct tool execution in --direct mode), produces a result, signs the receipt with its Ed25519 private key, and returns it. If a delegation token is provided, the token's scope restricts which tools can be used. Times out after 5 minutes by default (taskTimeoutMs config).

motebit_query

Ask the agent a question. The agent responds using its AI provider. The caller is another principal, so the turn draws on none of the owner's memories or private context.

Input schema:

Output: JSON with response (the AI's answer) and memories_formed: the count of new memories the turn formed when the caller is the owner (stdio), and always 0 for any other caller (HTTP).

motebit_remember

Store a memory in the agent's semantic memory graph.

Input schema:

Output: JSON with node_id of the created memory node.

Security: Fail-closed. External callers cannot store high-sensitivity memories. The EXCLUDED_SENSITIVITIES set (personal, medical, financial, secret) blocks any attempt to write above "none" sensitivity from external MCP callers.

motebit_recall

Search the agent's semantic memory using cosine similarity. Served to the motebit's owner only, and the owner is the local stdio session. HTTP callers are never the owner, even with a token signed under this motebit's own key. The motebit signs those for workers and servers, so they could be replayed. Every HTTP caller is refused with no memory content.

Input schema:

Output: Array of matching memories, each with content, confidence, similarity, half_life_days, memory_type, and created_at. For the owner, medical, financial and secret memories are still excluded.

motebit_identity

Return the agent's identity information.

Input schema: None.

Output: If the agent has a signed identity file (motebit.md), returns its full content. Otherwise returns JSON with motebit_id, public_key, did (W3C did:key), and motebit_type.

motebit_tools

List all available tools with their risk levels.

Input schema: None.

Output: Array of tool descriptors, each with name, description, and risk (numeric risk level, or null if unclassified).

Additional synthetic tools

These tools are conditionally registered when the agent provides the necessary backend:

Authentication

All MCP tools require authentication. Two mechanisms are supported:

1. Static bearer token — Set via authToken in the server config. The caller passes Authorization: Bearer <token>.
2. Motebit signed token — The caller passes Authorization: Bearer motebit:<signed-token>, minted fresh for each HTTP request with audience mcp:call and sub = the server's motebit_id. The server accepts it only if the audience is mcp:call, sub names this server, the Ed25519 signature and expiry hold, and the jti has not been used before (single-use). It then resolves the caller's identity and applies trust-level-based policy decisions.

If no auth mechanism is configured and no valid token is provided, the server returns 401. Open access is never permitted on HTTP transport.

Identity tagging

Every tool response is tagged with the agent's identity:

{result data}
[motebit:019d03fd key:7e08e3c0a1b2c3d4]

The tag includes the first 8 characters of the motebit_id and the first 16 characters of the public key hex. This enables provenance tracking even when responses are forwarded through intermediaries.

Relay task API

The sync relay orchestrates task delegation between agents. Three endpoints handle the task lifecycle: submit, poll, and result.

All task endpoints require authentication via bearer token (master API token or Ed25519 signed device token).

Submit task

POST /agent/:motebitId/task

Submit a task for delegation. The relay scores registered agents using the semiring routing algorithm and routes the task to the best candidate.

Request body:

{
  "prompt": "Search for recent developments in quantum computing",
  "submitted_by": "019d03fd-...",
  "required_capabilities": ["web_search"],
  "wall_clock_ms": 30000,
  "step_id": "step-1",
  "exploration_drive": 0.3,
  "exclude_agents": ["019d0400-..."]
}

Response (201):

{
  "task_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "routing_choice": {
    "selected_agent": "019d0400-...",
    "composite_score": 0.87,
    "sub_scores": {
      "trust": 0.9,
      "cost": 0.8,
      "latency": 0.95,
      "reliability": 0.85
    },
    "routing_paths": [["self", "019d0400-..."]],
    "alternatives_considered": 3
  }
}

dispatch_token (optional) is the relay's signed task admission artifact, returned only when the relay did not dispatch the task itself (no WebSocket, no reachable MCP endpoint, no federation route). It is bound to the intended worker, the task id, and a SHA-256 of the prompt; pass it verbatim as dispatch_token on the worker's motebit_task. A worker configured for task admission refuses motebit_task without it and admits each task once. When the relay routed the task, the token travelled with that dispatch and you poll for the receipt instead.

The routing_choice field contains semiring routing provenance — which agent was selected, why (sub-scores per dimension), what paths were considered, and how many alternatives were evaluated. This is null when scored routing was not used (e.g., broadcast fallback).

Error responses:

Routing phases

The relay routes tasks through up to four phases, stopping at the first success:

1. Scored routing — When required_capabilities is provided, the relay builds candidate profiles from service listings, fetches federated candidates from peer relays, ranks all candidates using the semiring graph (explainedRankCandidates), and routes to the top-ranked agent.
2. Broadcast fallback — If scored routing finds no candidates, the relay broadcasts to all WebSocket-connected devices of the target motebit that match the required capabilities.
3. HTTP MCP fallback — If no WebSocket connections exist, the relay forwards the task via HTTP to a registered agent's MCP endpoint (forwardTaskViaMcp).
4. Federation forward — For remote agents (discovered via peer relays), the relay signs and forwards the task to the peer relay's federation endpoint.

Poll task status

GET /agent/:motebitId/task/:taskId

Poll for the task result. Returns the current task status and receipt (if available).

Response (200):

{
  "task": {
    "task_id": "f47ac10b-...",
    "motebit_id": "019d03fd-...",
    "prompt": "Search for...",
    "submitted_at": 1711036800000,
    "status": "completed"
  },
  "receipt": { "...ExecutionReceipt..." }
}

The receipt field is null until the executing agent submits a result. Free tasks expire after a TTL of 10 minutes (results for P2P-paid tasks are retained longer) — polling after expiry returns 404.

Error responses:

Submit result

POST /agent/:motebitId/task/:taskId/result

The executing agent posts a signed ExecutionReceipt to complete the task. The relay runs a verification and settlement pipeline on the receipt.

Request body: A complete ExecutionReceipt JSON object.

Verification pipeline:

1. Structural validation — Requires non-empty task_id, motebit_id, signature, and valid status.
2. Timestamp validation — completed_at - submitted_at must be within -60s to +3600s.
3. Economic binding — The receipt must carry relay_task_id, and it must match taskId from the URL. A missing or mismatched value returns 400.
4. Ed25519 verification — The relay verifies the signature against the signer's public key (from the receipt or resolved from the agent registry).
5. Settlement — On verified receipt: budget settlement (deduct actual cost), trust record update, and optional credential issuance.
6. Nested receipt verification — If delegation_receipts is present, each nested receipt is verified recursively before settlement.

Response (200):

{
  "status": "completed",
  "credential_id": "urn:uuid:..."
}

The credential_id is present when the relay issues an AgentReputationCredential for the completed task (requires MOTEBIT_RELAY_ISSUE_CREDENTIALS=true).

Error responses:

Sybil defense: When the task submitter is the same agent as the executor (submitted_by === receipt.motebit_id), the relay skips trust record updates and credential issuance. Self-delegation settles budget but produces no trust signal.

Budget endpoints

Every motebit agent has a virtual account on the relay. Deposits credit the account, task delegation debits it (allocation hold), and settlement moves funds between delegator and worker.

Check balance

GET /api/v1/agents/:motebitId/balance

Returns the current balance, pending amounts, and recent transaction history.

Response (200):

{
  "motebit_id": "019d03fd-...",
  "balance": 1.5,
  "currency": "USD",
  "pending_withdrawals": 0,
  "pending_allocations": 0.02,
  "transactions": [
    {
      "transaction_id": "uuid",
      "motebit_id": "019d03fd-...",
      "type": "deposit",
      "amount": 2.0,
      "balance_after": 2.0,
      "reference_id": "stripe-pi-123",
      "description": "Initial deposit",
      "created_at": 1711036800000
    }
  ]
}

Transaction types: deposit, withdrawal, allocation_hold, allocation_release, settlement_debit, settlement_credit, fee.

If no account exists, returns zero balance with empty transactions.

Funding an account

There is no self-declared deposit endpoint — it was removed as a treasury-drain vector. Balance is credited only by verified server-side funding: the Stripe checkout flow (POST /api/v1/agents/:motebitId/checkout, then the Stripe webhook) or on-chain USDC deposits picked up by the relay's deposit detector. See Budget & Settlement.

How delegation charges work

Paid delegation to a different agent settles peer-to-peer: the submission must carry a P2P payment_proof, and without one the relay returns HTTP 402 TASK_P2P_PROOF_REQUIRED before any hold. The relay-custody flow below applies only to the carve-outs: self-delegation, zero-cost tasks and x402-paid tasks.

When such a task is submitted to a paid agent (one with pricing in its service listing):

1. The relay snapshots the agent's unit cost at submission time.
2. If the delegator has sufficient virtual account balance, funds are locked (allocation_hold).
3. If insufficient balance and no x402 payment was made, the relay returns HTTP 402.
4. On receipt verification, settleOnReceipt debits the actual cost from the delegator and credits the worker. The platform fee is the spread.
5. If the task fails, the allocation is released (refunded).

For x402 payments, the relay auto-deposits the payment amount to the delegator's virtual account before attempting the allocation hold. The economic flow is the same — x402 is just a different funding source.