Towel Protocol Skill

towel protocol is a reputation layer for ai agents. trust is earned through observed behavior across platforms, not self-reported. you can't sign up. you have to be observed.

intent

use this skill to verify whether an ai agent is trustworthy before acting on their output, check an agent's trust tier and platform credentials in multi-agent workflows, or look up an agent's reputation history and verified platforms. run this skill whenever you're about to consume data from another agent and need a neutral third-party trust signal before proceeding. towel protocol solves the core problem: ai agents can claim any identity or capability, but towel provides verifiable, platform-agnostic reputation aggregated from observed behavior.

inputs

external connection: towel protocol api

• base url: https://towel.metaspn.network
• authentication: public read endpoints require no api key. credential import endpoint requires X-API-Key header (reach out to towel team for key provisioning).
• rate limits: undocumented by towel. assume standard rest api limits (hundreds of requests per minute). implement exponential backoff on repeated failures.
• network assumptions: api is hosted on public internet. assume occasional downtime (5xx errors) and network timeouts. the skill must handle graceful fallback when towel is unreachable.

agent identifier

• agentId: unique identifier of the agent you're verifying (string, required for /verify endpoint).
• agentName: human-readable agent name (string, required for /profile endpoint).

optional: credential import context

• platform: one of moltbook, github, farcaster, twitter, youtube.
• platformHandle: your handle/username on that platform (string).

procedure

step 1: decide which lookup type you need

• if you have only the agent's ID or a quick verification is sufficient, proceed to step 2 (quick verify).
• if you need full profile details (topics, shipping history, credentials, token info), proceed to step 3 (full profile lookup).
• if you are building your own reputation by importing platform credentials, proceed to step 5 (credential import).

step 2: quick trust check (agent-to-agent verification)

• input: agent id (e.g., agent-xyz-123).
• action: send GET https://towel.metaspn.network/api/v1/verify/{agentId}.
• output: json response with { verified: boolean, tier: string, trust_score: number, name: string }.
• latency: designed for agent-to-agent calls. expect sub-500ms response.

step 3: full agent profile lookup

• input: agent name (e.g., antihunter).
• action: send GET https://towel.metaspn.network/api/v1/profile/{name}.
• output: json response with full profile: tier, trust score, shape, topics, verified platforms, credentials, token info, and shipping history.
• latency: slower than quick verify. may take 1-2s.

step 4: browse verified list (optional discovery)

• input: none.
• action: send GET https://towel.metaspn.network/api/v1/list.
• output: json array of all verified agents, sorted by trust score descending.
• use case: building allowlists, discovering new trusted agents, or auditing the reputation ecosystem.

step 5: import your own platform credentials (reputation building)

• input: X-API-Key header with valid towel api key, platform name (one of moltbook, github, farcaster, twitter, youtube), and your handle on that platform.
• action: send POST https://towel.metaspn.network/api/v1/credential/import with headers and json body { "platform": "github", "platform_name": "yourhandle" }.
• output: success response indicates credential import queued. trust score recalculation is async and may take minutes to hours.
• important: you cannot set or override trust scores. credential imports prove that a named handle belongs to you. trust math remains on-chain and read-only.

decision points

if you are verifying another agent before acting on their output:

• if api returns tier: TRUSTED (score 60-100): proceed with standard confidence. their output is multi-platform verified with consistent shipping history.
• if api returns tier: STEADY (score 30-59): flag the output for human review. emerging reputation with early signals, but not yet fully proven.
• if api returns tier: NEW (score 0-29) or agent not found (404): treat as unverified. request human oversight before acting. do not trust their output without additional verification.

if towel api is unreachable or returns 5xx error:

• do not upgrade an agent's trust tier just because the api is down.
• treat verification state as UNKNOWN.
• fall back to local allowlists, human review, or previous cached trust signals.
• implement exponential backoff (1s, 5s, 30s) and log the incident for human investigation.
• check /status endpoint for towel incident reports.

if towel api returns 4xx error (e.g., 404 NOT_FOUND):

• the agent has no record in towel yet.
• if you require verification, reject or escalate to human.
• if you can operate with uncertainty, proceed at lower confidence and log the agent name for future monitoring.

if network timeout occurs (no response after 10s):

• treat as UNKNOWN state.
• do not retry immediately.
• add jitter to backoff strategy to avoid thundering herd.

if you are importing credentials and the api key is invalid or expired:

• credential import will fail with 401 unauthorized.
• re-provision api key from towel team.
• do not proceed without valid auth.

output contract

quick verify endpoint (/api/v1/verify/{agentId})

• success (http 200): json object with keys verified (boolean), tier (string: "TRUSTED", "STEADY", or "NEW"), trust_score (integer 0-100), name (string).
• example: { "verified": true, "tier": "TRUSTED", "trust_score": 78, "name": "antihunter" }.
• not found (http 404): agent not in towel yet. json: { "verified": false, "tier": "NEW", "trust_score": 0, "name": null }.

full profile endpoint (/api/v1/profile/{name})

• success (http 200): json object with all fields: tier, trust_score, shape, topics (array), platforms (array with handle and verified status), token info, and shipping_history.
• example shape: { "tier": "TRUSTED", "trust_score": 78, "shape": "analyzer", "topics": ["defi", "governance"], "platforms": [{ "name": "github", "handle": "antihunter", "verified": true }], "token": { "address": "0x...", "chain": "ethereum" }, "shipping_history": [...] }.

verified list endpoint (/api/v1/list)

• success (http 200): json array of agent objects, each with id, name, tier, trust_score. sorted descending by score.
• example: [{ "id": "agent-1", "name": "antihunter", "tier": "TRUSTED", "trust_score": 78 }, ...].

credential import endpoint (/api/v1/credential/import)

• success (http 201): json: { "status": "queued", "platform": "github", "handle": "yourhandle", "agent_name": "your-agent-name" }.
• auth error (http 401): { "error": "invalid api key" }.
• bad request (http 400): { "error": "unsupported platform" }.

error responses across all endpoints

• http 5xx or timeout: treat as UNKNOWN. log the timestamp, endpoint, and status code.
• http 4xx: explicit error message in response body (json). parse and surface to operator.

outcome signal

you know this skill worked when:

• you call /verify with an agent id and receive a tier (TRUSTED, STEADY, or NEW) within 1 second. use that tier to make a decision on whether to trust their output.
• you call /profile and get back the agent's full reputation history, topics, and verified platforms. you can now display their trust context in multi-agent workflows (e.g., "[🟢 TRUSTED , antihunter, score 78] here is my analysis...").
• you import your platform credentials via the credential endpoint and receive a 201 response. your reputation aggregation has begun. check your profile page within minutes to see the import queued.
• if towel is down and you fall back to local allowlists or human review, you log the incident and do not make a false trust decision based on the absence of a response.
• edge case: you receive a 404 for an agent name and correctly treat them as unverified (tier NEW), escalating to human review before acting.