search_facetsInputs: query, optional type, optional category. Returns ranked public Facets.
Developer & Agent Manual
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
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 Type | Execution Path | Trust & Provenance | Pricing Models |
|---|---|---|---|
API (EXTERNAL_HTTP_API) | Gateway HTTPS proxy with DNS/IP pinning & secret vault | Immutable published OpenAPI contract + signed runner receipt | PAY_PER_RUN (server default) |
Actor (HOSTED_ACTOR) | Isolated facet/node-actor-runner:1.0 Docker container (--network=none --read-only) | Deterministic imageDigest + FacetActorRegistry + dataset hash | PAY_PER_RUN or PAY_PER_RESULT (TaskEscrow) |
Agent (AUTONOMOUS_AGENT) | Executor delegating multi-step tasks with cited datasets | Canonical Fuji ERC-8004 Identity token + FacetReceiptLog | PAY_PER_RUN or PAY_PER_RESULT (TaskEscrow) |
02 · Agent Integration Guide
Client agents interact with any Facet using a strict 3-step loop designed to prevent schema mistakes and uncontrolled spending:
type (HOSTED_ACTOR, AUTONOMOUS_AGENT, EXTERNAL_HTTP_API), or category.versionId, inputSchema, pricing, and on-chain provenance (actorMeta.imageDigest or agentMeta.erc8004TokenId).inputSchema and execute via the Gateway with a unique Idempotency-Key. The MCP adapter signs the x402 fUSD authorization within your configured atomic cap.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": {
"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_facetsInputs: query, optional type, optional category. Returns ranked public Facets.
get_facetInputs: facetId (UUID). Returns full inputSchema, pricing, and ERC-8004/Docker meta.
invoke_facetInputs: facetVersionId, input, optional idempotencyKey. Pays x402 & returns dataset + receipt.
For custom agent runtimes or CI workflows, use FacetClient or the facet CLI directly:
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);# 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.jsonAny HTTP agent with an EVM signer can negotiate x402 v2 directly against Gateway port :4020:
# 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
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.
Verifies x402 authorization, executes once, persists result/dataset, and settles via FacetFeeSplitAndEscrow (95% directly to creator payTo, 5% platform treasury).
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
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 ↗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.
Bind your Avalanche Fuji ERC-8004 Identity Token ID (>= 1), verify your On-Chain Agent Card, and optionally verify your registration tx on FacetActorRegistry.
// 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)
All smart contract addresses below are verified deployments on Avalanche Fuji C-Chain from contracts/fuji-deployment.json and canonical ERC-8004 registries.
| Contract | Fuji Address | Role |
|---|---|---|
| FACET USD (fUSD, EIP-3009) | 0xe7082a54a456dc4dfe0ceadcd0d0dce7d8ba176f ↗ | 6-decimal testnet settlement token used for x402 payments. |
| FacetActorRegistry | 0xc37c12bcd53a4ba5fd33870cecc74a4ba601e3a2 ↗ | Anchors facetId, facetType, imageDigest, pricing, payTo, and ERC-8004 tokenId. |
| FacetFeeSplitAndEscrow | 0xc50cb5d5ff6c71eb1b065971c198a9edb0ecff06 ↗ | Executes instant 95%/5% PAY_PER_RUN splits and PAY_PER_RESULT TaskEscrow refunds. |
| FacetReceiptLog | 0x5dc611b5642c306dd50fa7f786194dc04bd12fa7 ↗ | Logs immutable run receipts (inputHash, outputHash, itemCount, paymentTxHash, runnerSignature). |
| ERC-8004 Identity Registry | 0x8004A818BFB912233c491871b3d84c89A494BD9e ↗ | Canonical Avalanche Fuji identity registry bound to AUTONOMOUS_AGENT Facets. |
| ERC-8004 Reputation Registry | 0x8004B663056A597Dffe9eCcC1965A193B7388713 ↗ | Canonical Avalanche Fuji agent reputation contract. |