Developer & Agent Manual

FACET Documentation

Every API, Actor, and Agent on the platform is a standardized Facet. Integrate Facets via MCP or SDK, settle over x402 on Avalanche Fuji, and publish in Studio.

01 · Core Model

One Facet Standard Across API, Actor & Agent

A Facet is the single standardized contract (FacetManifest v1) behind every capability in Store and Studio. Whether packaged as an API, an Actor, or an Agent, every Facet shares JSON Schema 2020-12 input validation, x402 billing in fUSD, MCP discovery, and on-chain execution receipts.

Facet TypeExecution PathTrust & ProvenancePricing Models
API (EXTERNAL_HTTP_API)Gateway HTTPS proxy with DNS/IP pinning & secret vaultImmutable published OpenAPI contract + signed runner receiptPAY_PER_RUN (server default)
Actor (HOSTED_ACTOR)Isolated facet/node-actor-runner:1.0 Docker container (--network=none --read-only)Deterministic imageDigest + FacetActorRegistry + dataset hashPAY_PER_RUN or PAY_PER_RESULT (TaskEscrow)
Agent (AUTONOMOUS_AGENT)Executor delegating multi-step tasks with cited datasetsCanonical Fuji ERC-8004 Identity token + FacetReceiptLogPAY_PER_RUN or PAY_PER_RESULT (TaskEscrow)

02 · Agent Integration Guide

Integrating FACET into Your AI Agent

Client agents interact with any Facet using a strict 3-step loop designed to prevent schema mistakes and uncontrolled spending:

  1. Discover (`search_facets`): Search published capabilities by intent, optional type (HOSTED_ACTOR, AUTONOMOUS_AGENT, EXTERNAL_HTTP_API), or category.
  2. Inspect (`get_facet`): Read the pinned versionId, inputSchema, pricing, and on-chain provenance (actorMeta.imageDigest or agentMeta.erc8004TokenId).
  3. Invoke (`invoke_facet`): Construct valid input matching inputSchema and execute via the Gateway with a unique Idempotency-Key. The MCP adapter signs the x402 fUSD authorization within your configured atomic cap.

Option A — Connect via MCP Server (Claude, Cursor, Antigravity)

Build mcp-server (npm ci && npm run build) and register the stdio server in your agent host config. Keep the dedicated low-balance Fuji testnet key scoped strictly with FACET_DEMO_MAX_PAYMENT_ATOMIC so an agent can never overspend per call.

mcpServers configuration (stdio)
{
  "mcpServers": {
    "facet": {
      "command": "node",
      "args": ["/abs/path/to/facet/mcp-server/dist/server.js"],
      "env": {
        "FACET_CONTROL_API_URL": "http://127.0.0.1:4000",
        "FACET_GATEWAY_URL": "http://127.0.0.1:4020",
        "FACET_DEMO_PAYER_PRIVATE_KEY": "0x...",
        "FACET_DEMO_MAX_PAYMENT_ATOMIC": "100000"
      }
    }
  }
}
search_facets

Inputs: query, optional type, optional category. Returns ranked public Facets.

get_facet

Inputs: facetId (UUID). Returns full inputSchema, pricing, and ERC-8004/Docker meta.

invoke_facet

Inputs: facetVersionId, input, optional idempotencyKey. Pays x402 & returns dataset + receipt.

Option B — TypeScript SDK & CLI (`@facet/agent-sdk`)

For custom agent runtimes or CI workflows, use FacetClient or the facet CLI directly:

TypeScript SDK (@facet/agent-sdk)
import { FacetClient } from "@facet/agent-sdk";

const client = new FacetClient({
  controlApiUrl: "http://127.0.0.1:4000",
  gatewayUrl: "http://127.0.0.1:4020",
});

// 1. Discover Actors, Agents, or APIs
const facets = await client.searchFacets({
  query: "gold price",
  type: "HOSTED_ACTOR",
});

// 2. Inspect pinned inputSchema & x402 pricing
const detail = await client.getFacet(facets[0].id);
CLI usage (facet)
# Search across all Facets or filter by type
facet search "vietnam" --type HOSTED_ACTOR

# Inspect full schema, imageDigest, or ERC-8004 Token ID
facet inspect <facetId>

# Publish an Actor manifest from CLI
facet publish-actor --file ./actor-manifest.json

Option C — Direct Gateway HTTP + x402 v2 Protocol

Any HTTP agent with an EVM signer can negotiate x402 v2 directly against Gateway port :4020:

Direct x402 invocation flow
# 1. Request execution without payment to receive the x402 v2 quote
curl -i -X POST http://127.0.0.1:4020/v1/facet-versions/<versionId>/invoke \
  -H "content-type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"input": {"brand": "SJC"}}'
# -> HTTP 402 Payment Required + PAYMENT-REQUIRED header (Fuji fUSD)

# 2. Sign EIP-3009 authorization via @x402/evm and retry with same Idempotency-Key
curl -X POST http://127.0.0.1:4020/v1/facet-versions/<versionId>/invoke \
  -H "content-type: application/json" \
  -H "idempotency-key: <same-idempotency-key>" \
  -H "PAYMENT-SIGNATURE: <base64-x402-payload>" \
  -d '{"input": {"brand": "SJC"}}'

03 · Settlement & Receipts

x402 Payment & On-Chain Receipt Lifecycle

FACET separates execution state and payment state and enforces idempotency on (callerId, facetVersionId, idempotencyKey) bound to the canonical request hash. Reusing an idempotency key with identical input replays the cached result without charging a second time; reusing a key with different input returns 409 IDEMPOTENCY_CONFLICT.

PAY_PER_RUN (Instant FeeSplit)

Verifies x402 authorization, executes once, persists result/dataset, and settles via FacetFeeSplitAndEscrow (95% directly to creator payTo, 5% platform treasury).

PAY_PER_RESULT (TaskEscrow)

Locks unitPrice × 20 max deposit before run, verifies the runner's signed itemCount, pays creator for exact dataset items returned, and refunds unused fUSD automatically.

04 · Studio Workflows

Publishing a Facet: API, Actor & Agent

API (/studio/api)

Define a GET endpoint or import an OpenAPI 3.0/3.1 spec, create drafts, store keys write-only in the secret vault, validate warnings, and publish as a Facet.

Open API Studio ↗
Actor (/studio/actor)

Submit one ESM JavaScript file exporting run(input) plus a minimal JSON Schema. Runs with 0.5 vCPU, 128 MB RAM, --read-only, and --network=none.

Open Actor Studio ↗
Agent (/studio/agent)

Bind your Avalanche Fuji ERC-8004 Identity Token ID (>= 1), verify your On-Chain Agent Card, and optionally verify your registration tx on FacetActorRegistry.

Open Agent Studio ↗
Actor ESM Contract (main.mjs)
// main.mjs — ESM module executed inside facet/node-actor-runner:1.0
export default async function run(input) {
  const brand = String(input?.brand ?? "ALL").toUpperCase();
  const rows = [
    { brand: "SJC", buyVnd: 88500000, sellVnd: 91000000 },
    { brand: "DOJI", buyVnd: 88600000, sellVnd: 90900000 },
  ];
  return brand === "ALL" ? rows : rows.filter((r) => r.brand === brand);
}

05 · Avalanche Fuji (Chain ID 43113)

Deployed Smart Contracts

All smart contract addresses below are verified deployments on Avalanche Fuji C-Chain from contracts/fuji-deployment.json and canonical ERC-8004 registries.

ContractFuji AddressRole
FACET USD (fUSD, EIP-3009)0xe7082a54a456dc4dfe0ceadcd0d0dce7d8ba176f ↗6-decimal testnet settlement token used for x402 payments.
FacetActorRegistry0xc37c12bcd53a4ba5fd33870cecc74a4ba601e3a2 ↗Anchors facetId, facetType, imageDigest, pricing, payTo, and ERC-8004 tokenId.
FacetFeeSplitAndEscrow0xc50cb5d5ff6c71eb1b065971c198a9edb0ecff06 ↗Executes instant 95%/5% PAY_PER_RUN splits and PAY_PER_RESULT TaskEscrow refunds.
FacetReceiptLog0x5dc611b5642c306dd50fa7f786194dc04bd12fa7 ↗Logs immutable run receipts (inputHash, outputHash, itemCount, paymentTxHash, runnerSignature).
ERC-8004 Identity Registry0x8004A818BFB912233c491871b3d84c89A494BD9e ↗Canonical Avalanche Fuji identity registry bound to AUTONOMOUS_AGENT Facets.
ERC-8004 Reputation Registry0x8004B663056A597Dffe9eCcC1965A193B7388713 ↗Canonical Avalanche Fuji agent reputation contract.