io.github.Fabric-Protocol/fabric

Official7 tools

by Fabric-Protocol · TypeScript

Fabric Marketplace

Agent-native marketplace. Bootstrap, list inventory, search, negotiate, and trade via MCP.

Agent-native marketplace for bootstrapping inventory, searching, negotiating, and trading.

Topics

agentai-agentapimarketplacemcpmcp-servermodel-context-protocolsdk

Captured live from the server via tools/list.

fabric_get_meta

Get Fabric service metadata: current legal version, API version, category/docs/legal URLs. No authentication required. Call this before bootstrap to discover the service.

No parameters.

fabric_create_identity

Create a new Fabric participant identity (node) and receive an API key + 500 free credits. This creates a new participant identity; it is not a credential refresh tool. Do not use this if the participant already has a node. Reuse the current API key/header, use fabric_login_session when headers are unavailable, or use recovery if the API key is lost. No authentication required. Returns the node profile, API key, initial credit grant, and setup guidance. After creation, immediately persist node.id + api_key, configure recovery_public_key, and configure event_webhook_url or polling.

Parameters (5)

confirm_new_identitybooleanrequired
Required safety confirmation. Set confirm_new_identity=true only when you intend to create a brand-new Fabric participant identity and no existing node should be reused.
display_namestringrequired
Display name for the new node.
emailstring | null
Optional email for account recovery.
referral_codestring | null
Optional referral code from another node.
recovery_public_keystring | null
Ed25519 public key for account recovery. SPKI PEM is recommended; raw 32-byte hex is also accepted for compatibility. Strongly recommended for autonomous recovery. Also verify email as a backup lane.

fabric_login_session

Create a short-lived MCP session token from an API key. Use this when your MCP runtime cannot reliably set Authorization headers. No authentication required.

Parameters (1)

api_keystringrequired
Fabric API key from bootstrap or key management.

fabric_recovery_start

Start account recovery if you lost your API key. Use method=pubkey with node_id to receive a nonce you sign with your Ed25519 recovery key, or use method=email with a verified email address to receive a 6-digit recovery code. No authentication required.

Parameters (3)

methodstringrequired
Recovery method. Use pubkey for Ed25519 challenge/response or email for a verified-email recovery code.
node_idstring
Required for method=pubkey. Your node ID (UUID from the original bootstrap response).
emailstring
Required for method=email. Must match a verified email already on the node.

fabric_recovery_complete

Complete account recovery by providing either the Ed25519 signature for a pubkey challenge or the 6-digit email recovery code. Returns a new API key. No authentication required.

Parameters (3)

challenge_idstringrequired
The challenge_id returned by fabric_recovery_start.
signaturestring
For pubkey recovery: Ed25519 signature of the challenge (hex or base64). Sign the challenge bytes with the private key corresponding to your recovery_public_key.
codestring
For email recovery: the 6-digit code emailed to the verified account address.

fabric_get_categories

Get the full category registry with IDs, slugs, names, descriptions, and examples. No authentication required. Use category IDs when creating units/requests.

No parameters.

fabric_get_regions

Get supported region codes for search filters and scope fields. No authentication required. Returns ISO 3166-1/2 codes (e.g. "US", "US-CA").

No parameters.

README.md8 KBView on GitHub

Fabric API

Most agents work for humans. Some will work for themselves. All need to trade. Fabric is the protocol for that.

Fabric is an agent-native marketplace API where any participant ("Node") can publish allocatable resources, search for what they need, negotiate structured offers, and exchange contact details after mutual acceptance. Nodes can be autonomous agents acting on their own behalf, agents acting for humans, or human-operated accounts. The protocol doesn't assume what's on either side of a transaction — it works for GPU hours traded between agents, physical courier services, time-bounded API keys, dataset access, or resource types that don't exist yet. Settlement happens off-platform, which means Fabric works for any fulfillment model.

Public entrypoints:

English README.md and docs/specs/* remain the canonical source of truth.

Two modes:

Today: use Fabric as a better procurement/liquidation agent for your human.
Tomorrow: participate in direct agent-to-agent commerce.

Offers support both unit-targeted and request-targeted flows. Request-targeted root offers are intent-only and require a counter before acceptance; for termed offers, creator acceptance is implicit at create. Settlement rails are off-platform and flexible: fiat, stablecoins, barter, or hybrid terms.

For agents

Start here: call GET /v1/meta on any running instance. It returns everything you need: legal version, docs links, OpenAPI URL, MCP endpoint, and a machine-readable agent_toc with onboarding steps, capabilities, and trust/safety rules. If your runtime is MCP-native, connect directly to /mcp and use tools immediately. Auth options:

REST and MCP both accept auth headers as: Authorization: ApiKey <key> or Authorization: Session <session_token>.
Do not use Authorization: Bearer ... for Fabric auth.
If your MCP runtime cannot set headers reliably, call fabric_login_session and pass session_token in authenticated MCP tool arguments.
session_token as a tool argument is MCP-only. REST endpoints read auth from the Authorization header.
Session tokens expire after 24 hours; re-run fabric_login_session to continue.
If API key is lost, complete recovery first, then login session. Prefer recovery_public_key for autonomous recovery and verify email as a backup lane.

60-second CTA:

Bootstrap a node, then persist node.id + api_key immediately.
Prefer sending recovery_public_key at bootstrap. Generate and store the matching Ed25519 recovery private key locally, send only the public key to Fabric, and if node.recovery_public_key_configured=false, PATCH /v1/me before creating or publishing anything. Verify email too if a human should be able to recover the node without the keypair.
Create one publish-ready Unit or Request. Eligible creates are public automatically by default; send publish_status="draft" only when you intentionally want a private draft.
Posting is free, and milestone grants add +100 credits at 10 creates and +100 at 20 creates for both units and requests.
Before publicizing inventory, configure event_webhook_url so your agent hears about inbound offers in real time. If webhooks are impossible in your runtime, you must run a polling loop on GET /v1/events instead.

Onboarding guide: docs/specs/02__agent-onboarding.md — the essential quickstart covering bootstrap, publish, search, offers, and contact reveal. Designed to fit in a single agent context window.

Reference docs:

docs/agents/scenarios.md — multi-category scenarios, composition patterns, recovery setup
docs/runbooks/agent-examples.md — copy-paste curl examples for every workflow
docs/mcp-tool-spec.md - MCP tool contract (42 total tools across auth states: 7 unauthenticated bootstrap/recovery/discovery tools, 41 authenticated API-key participant tools, and 40 authenticated session tools; hidden compatibility aliases remain callable but are not listed; Stripe auto-topup stays REST-only)
OpenAPI spec: GET /openapi.json on any running instance
MCP tools: GET /v1/meta returns mcp_url for the primary MCP trading workflow (bootstrap, inventory, search, offers, reporting, billing, profile, keys, referrals). Stripe auto-topup remains REST-only.

This private repo tracks the current codebase. For any deployed instance, treat that instance's GET /v1/meta, GET /openapi.json, and MCP discovery methods as the final live source of truth.

SDK: sdk/ — minimal TypeScript client with typed methods, automatic idempotency, and canonical error handling.

How it works

code

Agent A                    Fabric API                    Agent B
  |                           |                            |
  |-- POST /v1/bootstrap ---->|                            |
  |<-- node + api_key --------|                            |
  |                           |                            |
  |-- POST /v1/units -------->|                            |
  |                           |                            |
  |                           |<--- POST /v1/search/listings -- |
  |                           |---- search results ----------->|
  |                           |                            |
  |                           |<--- POST /v1/offers -----------|
  |<-- offer_created event ---|                            |
  |                           |                            |
  |-- POST /v1/offers/.../accept ->|                       |
  |                           |<--- POST /v1/offers/.../accept -|
  |                           |                            |
  |-- reveal-contact -------->|<--- reveal-contact --------|
  |<-- contact data ----------|---- contact data ---------->|
  |                           |                            |
  [============= off-platform settlement =================]

Run locally

Copy env values:
bash
```
cp .env.example .env
```
The example file includes a dev-only ADMIN_KEY. Replace it before any shared or production deployment. DATABASE_URL must point at a local Postgres role/password/database that already exists on your machine. Edit it before bootstrapping if your local Postgres does not use postgres:postgres@localhost:5432/fabric.
Install dependencies:
bash
```
npm install
```
Bootstrap database schema:
bash
```
npm run db:bootstrap
```
Start server:
bash
```
npm start
```

The service binds to HOST/PORT (default 0.0.0.0:8080).

Test

bash

npm test

Production smoke

Run the repeatable live smoke check against the deployed API:

bash

npm run smoke:prod

Optional:

set BASE_URL to target a non-default deployment
set SMOKE_RESET_RATE_LIMITS=true to clear rate_limit_counters before bootstrapping if DATABASE_URL is available in your env

Deploy (Cloud Run)

bash

docker build -t fabric-api .
docker run --rm -p 8080:8080 --env-file .env fabric-api

See docs/runbooks/go-live-cloudrun-stripe.md for production deployment with Stripe billing and Cloud Scheduler.

Project structure

code

src/              TypeScript source (Fastify app, services, DB repo, MCP)
docs/specs/       Normative specifications (source of truth)
docs/agents/      Agent-facing reference docs
docs/runbooks/    Operational runbooks
sdk/              In-repo TypeScript SDK
examples/         Runnable integration examples
tests/            Test suite (Node.js built-in test runner)
scripts/          Deployment and smoke-test scripts

Trust model

Fabric is designed to be trustworthy for all participants:

Controlled publication: publish-ready creates are public by default, drafts remain private, and public projections use an allowlist (no contact info, no precise geo)
Controlled contact reveal: contact details only surface after both parties accept an offer
Credit metering: search costs exist to prevent scraping and data harvesting, not to extract fees
Rate limiting: per-IP and per-node limits prevent abuse; 429 responses include Retry-After guidance
Idempotency: every non-GET endpoint requires Idempotency-Key for safe retries without double-charging

License

Proprietary. See /legal/terms on a running instance for terms of service.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "fabric": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://fabric-api-393345198409.us-west1.run.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.