Physical Capability Cloud

Official255 toolsLive

by LamaSu · TypeScript

Discover, hire, and verify real-world physical capability through MCP.

Captured live from the server via tools/list.

provision_api_key

CALL THIS FIRST. Provisions an API key for the operator. Returns a pcc_live_* key that must be included as 'Authorization: Bearer <key>' on all subsequent requests. Accepts either email OR walletAddress. The key is shown once — save it. Without it, all other endpoints return 401.

Parameters4

email	string	optional	Operator email address (use this OR walletAddress)
walletAddress	string	optional	EVM wallet address (use this OR email)
name	string	optional	Operator display name (optional)
capability	string	optional	What the operator does — e.g. 'FDM 3D printing', 'CNC milling', 'HPLC analysis'

Raw schema

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "Operator email address (use this OR walletAddress)"
    },
    "walletAddress": {
      "type": "string",
      "description": "EVM wallet address (use this OR email)"
    },
    "name": {
      "type": "string",
      "description": "Operator display name (optional)"
    },
    "capability": {
      "type": "string",
      "description": "What the operator does — e.g. 'FDM 3D printing', 'CNC milling', 'HPLC analysis'"
    }
  },
  "required": []
}

list_api_keys

List all active API keys for the authenticated operator. Returns key IDs, prefixes, scopes, rate limits, usage counts, and creation/expiry timestamps. Requires a valid API key or SIWE session.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

revoke_api_key

Revoke an API key permanently. The key will immediately stop working. You must own the key. Use list_api_keys to find the key ID.

Parameters1

keyId

string

required

Key ID to revoke (from list_api_keys)

Raw schema

{
  "type": "object",
  "properties": {
    "keyId": {
      "type": "string",
      "description": "Key ID to revoke (from list_api_keys)"
    }
  },
  "required": [
    "keyId"
  ]
}

setup_detect

Auto-detect current setup state: env vars, database, adapters, chain connectivity, storage, identity. Use this to see what's configured and what's missing before onboarding.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

setup_generate_config

Generate a KERNEL_CONFIG JSON from device descriptions. Tell it what machines you have and it produces the config ready to paste into your environment.

Parameters1

devices

array

required

Array of device descriptions with type, model, and connection info

Raw schema

{
  "type": "object",
  "properties": {
    "devices": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Array of device descriptions with type, model, and connection info"
    }
  },
  "required": [
    "devices"
  ]
}

setup_validate

Validate a kernel config (20+ checks: JSON structure, device connectivity, adapter compatibility). Returns validation errors and warnings.

Parameters1

config

object

required

Kernel config JSON to validate

Raw schema

{
  "type": "object",
  "properties": {
    "config": {
      "type": "object",
      "description": "Kernel config JSON to validate"
    }
  },
  "required": [
    "config"
  ]
}

setup_register_device

Parameters5

kernelId	string	required	Kernel ID to register the device under
type	string	required	Device type (e.g. fdm-printer, cnc-mill, hplc)
model	string	required	Device model identifier
adapterType	string	optional	Adapter type: octoprint, modbus, opcua, sila, opentrons, generic-http
adapterConfig	object	optional	Adapter-specific configuration (host, port, auth, etc.)

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to register the device under"
    },
    "type": {
      "type": "string",
      "description": "Device type (e.g. fdm-printer, cnc-mill, hplc)"
    },
    "model": {
      "type": "string",
      "description": "Device model identifier"
    },
    "adapterType": {
      "type": "string",
      "description": "Adapter type: octoprint, modbus, opcua, sila, opentrons, generic-http"
    },
    "adapterConfig": {
      "type": "object",
      "description": "Adapter-specific configuration (host, port, auth, etc.)"
    }
  },
  "required": [
    "kernelId",
    "type",
    "model"
  ]
}

setup_test_job

Submit a test job to verify the full pipeline works end-to-end (Step 4 of onboarding). Returns job ID and result.

Parameters2

kernelId	string	required	Kernel ID to test
deviceId	string	optional	Specific device ID to test (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to test"
    },
    "deviceId": {
      "type": "string",
      "description": "Specific device ID to test (optional)"
    }
  },
  "required": [
    "kernelId"
  ]
}

setup_status

Comprehensive setup status across 6 categories: gateway, database, adapters, chain, storage, identity. Use to confirm everything is green before going live.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

list_capability_types

List all capability types registered on the network (FDM, SLA, CNC, HPLC, etc.) with metadata.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

search_capabilities

Search capability templates by type or keyword. Returns templates with pricing, assurance tiers, and availability.

Parameters1

query

string

required

Search query (type name, material, process, etc.)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query (type name, material, process, etc.)"
    }
  },
  "required": [
    "query"
  ]
}

get_build_options

Get configuration options for a capability type (materials, dimensions, tolerances, assurance tiers). Use before calling calculate_price.

Parameters3

type	string	required	Capability type (e.g. fdm, cnc-3axis, hplc)
selections	object	optional	Current selections to refine available options
profileId	string	optional	Optional capability profile ID

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Capability type (e.g. fdm, cnc-3axis, hplc)"
    },
    "selections": {
      "type": "object",
      "description": "Current selections to refine available options"
    },
    "profileId": {
      "type": "string",
      "description": "Optional capability profile ID"
    }
  },
  "required": [
    "type"
  ]
}

calculate_price

Calculate price for a capability configuration. Returns base price, tier premiums, and estimated total cost.

Parameters3

type	string	required	Capability type
selections	object	required	Configuration selections (material, dimensions, quantity, etc.)
profileId	string	optional	Optional capability profile ID

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Capability type"
    },
    "selections": {
      "type": "object",
      "description": "Configuration selections (material, dimensions, quantity, etc.)"
    },
    "profileId": {
      "type": "string",
      "description": "Optional capability profile ID"
    }
  },
  "required": [
    "type",
    "selections"
  ]
}

build_contract

Build and submit a capability contract with on-chain milestone escrow. Returns job ID and escrow address.

Parameters4

type	string	required	Capability type
selections	object	required	Configuration selections
assuranceTier	number	required	Assurance tier 0-3 (0=self-reported, 3=ZK-proven+bonds)
profileId	string	optional	Optional capability profile ID

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Capability type"
    },
    "selections": {
      "type": "object",
      "description": "Configuration selections"
    },
    "assuranceTier": {
      "type": "number",
      "description": "Assurance tier 0-3 (0=self-reported, 3=ZK-proven+bonds)"
    },
    "profileId": {
      "type": "string",
      "description": "Optional capability profile ID"
    }
  },
  "required": [
    "type",
    "selections",
    "assuranceTier"
  ]
}

list_kernels

List all Shop Kernels on the network with status and capability types. Optionally filter by status.

Parameters1

status

string

optional

Filter by kernel status (online, offline, maintenance)

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter by kernel status (online, offline, maintenance)"
    }
  },
  "required": []
}

get_kernel

Get kernel details including full capability objects, devices, and queue.

Parameters1

kernelId

string

required

Kernel ID

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID"
    }
  },
  "required": [
    "kernelId"
  ]
}

get_kernel_devices

List all devices registered under a specific kernel, including adapter configs and device types.

Parameters1

kernelId

string

required

Kernel ID

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID"
    }
  },
  "required": [
    "kernelId"
  ]
}

get_kernel_jobs

List all jobs submitted to a specific kernel, including job status and progress.

Parameters1

kernelId

string

required

Kernel ID

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID"
    }
  },
  "required": [
    "kernelId"
  ]
}

create_kernel

Parameters4

name	string	required	Kernel/site name (e.g. 'BioPunk Lab - Bay A')
description	string	optional	Description of the site and its capabilities
location	object	optional	Location object with address and geo coordinates
config	object	optional	Kernel configuration JSON

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Kernel/site name (e.g. 'BioPunk Lab - Bay A')"
    },
    "description": {
      "type": "string",
      "description": "Description of the site and its capabilities"
    },
    "location": {
      "type": "object",
      "description": "Location object with address and geo coordinates"
    },
    "config": {
      "type": "object",
      "description": "Kernel configuration JSON"
    }
  },
  "required": [
    "name"
  ]
}

list_jobs

List all jobs with status. Optionally filter by kernelId or status.

Parameters2

kernelId	string	optional	Filter by kernel ID
status	string	optional	Filter by status (pending, queued, in_progress, paused, completed, failed, cancelled)

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Filter by kernel ID"
    },
    "status": {
      "type": "string",
      "description": "Filter by status (pending, queued, in_progress, paused, completed, failed, cancelled)"
    }
  },
  "required": []
}

get_job

Get job details including progress, evidence bundles, and milestones.

Parameters1

jobId

string

required

Job ID

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Job ID"
    }
  },
  "required": [
    "jobId"
  ]
}

update_job_status

Update a job's status and optional progress percentage. Used by kernels to report job progress.

Parameters3

jobId	string	required	Job ID
status	string	required	New status (pending, queued, in_progress, paused, completed, failed, cancelled). 'running' is accepted as a legacy alias for in_progress.
progress	number	optional	Progress percentage 0-100 (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Job ID"
    },
    "status": {
      "type": "string",
      "description": "New status (pending, queued, in_progress, paused, completed, failed, cancelled). 'running' is accepted as a legacy alias for in_progress."
    },
    "progress": {
      "type": "number",
      "description": "Progress percentage 0-100 (optional)"
    }
  },
  "required": [
    "jobId",
    "status"
  ]
}

list_escrows

List escrow contracts with milestones and bonds. Optionally filter by status.

Parameters1

status

string

optional

Filter by escrow status

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter by escrow status"
    }
  },
  "required": []
}

get_escrow

Get escrow details. Pass a DB ID for database record (with milestones and disputes), or an EVM address (0x...) to read directly from the blockchain.

Parameters1

escrowId

string

required

DB escrow ID or on-chain contract address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "escrowId": {
      "type": "string",
      "description": "DB escrow ID or on-chain contract address (0x...)"
    }
  },
  "required": [
    "escrowId"
  ]
}

get_escrow_chain_state

Read full on-chain escrow state with all milestone details from the blockchain. More detailed than get_escrow for on-chain contracts.

Parameters1

address

string

required

On-chain escrow contract address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "On-chain escrow contract address (0x...)"
    }
  },
  "required": [
    "address"
  ]
}

get_escrow_events

Get on-chain event history for an escrow contract. Returns funding, release, dispute, and bond events.

Parameters2

address	string	required	On-chain escrow contract address (0x...)
fromBlock	string	optional	Starting block number (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "On-chain escrow contract address (0x...)"
    },
    "fromBlock": {
      "type": "string",
      "description": "Starting block number (optional)"
    }
  },
  "required": [
    "address"
  ]
}

get_token_balance

Read an ERC-20 token balance for an account address from the blockchain.

Parameters2

tokenAddress	string	required	ERC-20 token contract address (0x...)
account	string	required	Account address to check balance for (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "tokenAddress": {
      "type": "string",
      "description": "ERC-20 token contract address (0x...)"
    },
    "account": {
      "type": "string",
      "description": "Account address to check balance for (0x...)"
    }
  },
  "required": [
    "tokenAddress",
    "account"
  ]
}

get_token_allowance

Read the ERC-20 token allowance granted by an owner to a spender from the blockchain.

Parameters3

tokenAddress	string	required	ERC-20 token contract address (0x...)
owner	string	required	Token owner address (0x...)
spender	string	required	Spender address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "tokenAddress": {
      "type": "string",
      "description": "ERC-20 token contract address (0x...)"
    },
    "owner": {
      "type": "string",
      "description": "Token owner address (0x...)"
    },
    "spender": {
      "type": "string",
      "description": "Spender address (0x...)"
    }
  },
  "required": [
    "tokenAddress",
    "owner",
    "spender"
  ]
}

get_escrow_dispute

Read dispute state for a specific milestone from the blockchain.

Parameters2

address	string	required	Escrow contract address (0x...)
milestoneIndex	number	required	Milestone index (0-based)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Escrow contract address (0x...)"
    },
    "milestoneIndex": {
      "type": "number",
      "description": "Milestone index (0-based)"
    }
  },
  "required": [
    "address",
    "milestoneIndex"
  ]
}

get_write_status

Check if on-chain write operations are enabled (requires PCC_GATEWAY_PRIVATE_KEY to be configured). Returns write status and signer address.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

fund_escrow

Fund an escrow contract on-chain. The payer must have already approved the token transfer (use approve_token first). Returns transaction hash.

Parameters1

address

string

required

Escrow contract address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Escrow contract address (0x...)"
    }
  },
  "required": [
    "address"
  ]
}

approve_token

Approve ERC-20 token spending for an escrow contract on-chain. Call this before fund_escrow. Returns transaction hash.

Parameters3

address	string	required	Escrow contract address (0x...) to approve as spender
amount	string	required	Amount to approve in wei (as string to avoid precision loss)
tokenAddress	string	optional	ERC-20 token address to approve (optional, uses default if omitted)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Escrow contract address (0x...) to approve as spender"
    },
    "amount": {
      "type": "string",
      "description": "Amount to approve in wei (as string to avoid precision loss)"
    },
    "tokenAddress": {
      "type": "string",
      "description": "ERC-20 token address to approve (optional, uses default if omitted)"
    }
  },
  "required": [
    "address",
    "amount"
  ]
}

release_milestone

Release a milestone payment on-chain after the challenge window has expired. Returns transaction hash.

Parameters2

address	string	required	Escrow contract address (0x...)
milestoneIndex	number	required	Milestone index to release (0-based)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Escrow contract address (0x...)"
    },
    "milestoneIndex": {
      "type": "number",
      "description": "Milestone index to release (0-based)"
    }
  },
  "required": [
    "address",
    "milestoneIndex"
  ]
}

file_escrow_dispute

File a dispute against a milestone on-chain. Challenger must post a bond and provide evidence hash. Returns transaction hash.

Parameters5

address	string	required	Escrow contract address (0x...)
milestoneIndex	number	required	Milestone index to dispute (0-based)
challengerBond	string	required	Bond amount in wei (as string)
challengerEvidenceHash	string	required	Evidence hash as 0x-prefixed hex bytes32
reason	string	required	Human-readable dispute reason

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Escrow contract address (0x...)"
    },
    "milestoneIndex": {
      "type": "number",
      "description": "Milestone index to dispute (0-based)"
    },
    "challengerBond": {
      "type": "string",
      "description": "Bond amount in wei (as string)"
    },
    "challengerEvidenceHash": {
      "type": "string",
      "description": "Evidence hash as 0x-prefixed hex bytes32"
    },
    "reason": {
      "type": "string",
      "description": "Human-readable dispute reason"
    }
  },
  "required": [
    "address",
    "milestoneIndex",
    "challengerBond",
    "challengerEvidenceHash",
    "reason"
  ]
}

deposit_bond

Deposit an operator bond for a milestone on-chain. Required for Assurance Tier 3 jobs. Returns transaction hash.

Parameters2

address	string	required	Escrow contract address (0x...)
milestoneIndex	number	required	Milestone index to post bond for (0-based)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Escrow contract address (0x...)"
    },
    "milestoneIndex": {
      "type": "number",
      "description": "Milestone index to post bond for (0-based)"
    }
  },
  "required": [
    "address",
    "milestoneIndex"
  ]
}

submit_evidence_hash

Submit an evidence bundle hash for a milestone on-chain. Links the physical evidence to the on-chain settlement record. Returns transaction hash.

Parameters3

address	string	required	Escrow contract address (0x...)
milestoneIndex	number	required	Milestone index (0-based)
evidenceBundleHash	string	required	Evidence bundle hash as 0x-prefixed hex bytes32

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Escrow contract address (0x...)"
    },
    "milestoneIndex": {
      "type": "number",
      "description": "Milestone index (0-based)"
    },
    "evidenceBundleHash": {
      "type": "string",
      "description": "Evidence bundle hash as 0x-prefixed hex bytes32"
    }
  },
  "required": [
    "address",
    "milestoneIndex",
    "evidenceBundleHash"
  ]
}

submit_attestation

Submit a verifier attestation for a milestone on-chain. Used by third-party verifiers (Bittensor subnet) to confirm evidence quality. Returns transaction hash.

Parameters3

address	string	required	Escrow contract address (0x...)
milestoneIndex	number	required	Milestone index (0-based)
attestationHash	string	required	Attestation hash as 0x-prefixed hex bytes32

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Escrow contract address (0x...)"
    },
    "milestoneIndex": {
      "type": "number",
      "description": "Milestone index (0-based)"
    },
    "attestationHash": {
      "type": "string",
      "description": "Attestation hash as 0x-prefixed hex bytes32"
    }
  },
  "required": [
    "address",
    "milestoneIndex",
    "attestationHash"
  ]
}

archive_evidence

Archive an evidence bundle to IPFS/Storacha for permanent decentralized storage. Returns the content-addressed CID.

Parameters1

bundle

object

required

Evidence bundle object to archive

Raw schema

{
  "type": "object",
  "properties": {
    "bundle": {
      "type": "object",
      "description": "Evidence bundle object to archive"
    }
  },
  "required": [
    "bundle"
  ]
}

get_evidence_bundle

Get an encrypted evidence bundle by its bundle ID. Returns the encrypted payload and key capsules.

Parameters1

bundleId

string

required

Evidence bundle ID

Raw schema

{
  "type": "object",
  "properties": {
    "bundleId": {
      "type": "string",
      "description": "Evidence bundle ID"
    }
  },
  "required": [
    "bundleId"
  ]
}

grant_evidence_access

Grant a new recipient access to an encrypted evidence bundle. Creates a re-encrypted key capsule for the recipient.

Parameters3

bundleId	string	required	Evidence bundle ID
recipientAddress	string	required	Recipient EVM address (0x...)
accessLevel	string	optional	Level of access to grant (default: full)

Raw schema

{
  "type": "object",
  "properties": {
    "bundleId": {
      "type": "string",
      "description": "Evidence bundle ID"
    },
    "recipientAddress": {
      "type": "string",
      "description": "Recipient EVM address (0x...)"
    },
    "accessLevel": {
      "type": "string",
      "enum": [
        "full",
        "selective",
        "summary_only"
      ],
      "description": "Level of access to grant (default: full)"
    }
  },
  "required": [
    "bundleId",
    "recipientAddress"
  ]
}

list_evidence_grants

List all evidence access grants for an address. Returns bundles the address has been granted access to.

Parameters1

address

string

required

EVM address to look up grants for (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "EVM address to look up grants for (0x...)"
    }
  },
  "required": [
    "address"
  ]
}

archive_encrypted_bundle

Archive an encrypted evidence bundle to IPFS and store the resulting CID in the database. Idempotent — returns existing CID if already archived.

Parameters1

bundleId

string

required

Encrypted evidence bundle ID

Raw schema

{
  "type": "object",
  "properties": {
    "bundleId": {
      "type": "string",
      "description": "Encrypted evidence bundle ID"
    }
  },
  "required": [
    "bundleId"
  ]
}

get_bundle_ipfs

Get IPFS CIDs for a bundle — returns the primary CID, metadata CID, and Filecoin deal ID if available.

Parameters1

bundleId

string

required

Evidence bundle ID

Raw schema

{
  "type": "object",
  "properties": {
    "bundleId": {
      "type": "string",
      "description": "Evidence bundle ID"
    }
  },
  "required": [
    "bundleId"
  ]
}

retrieve_ipfs

Retrieve raw data from IPFS by CID. Used to fetch archived evidence bundles from decentralized storage.

Parameters1

cid

string

required

IPFS content identifier (CID)

Raw schema

{
  "type": "object",
  "properties": {
    "cid": {
      "type": "string",
      "description": "IPFS content identifier (CID)"
    }
  },
  "required": [
    "cid"
  ]
}

get_lit_conditions

Get Lit Protocol access conditions for a Lit-encrypted evidence bundle. Returns the conditions that gate decryption.

Parameters1

bundleId

string

required

Evidence bundle ID (must be Lit-encrypted)

Raw schema

{
  "type": "object",
  "properties": {
    "bundleId": {
      "type": "string",
      "description": "Evidence bundle ID (must be Lit-encrypted)"
    }
  },
  "required": [
    "bundleId"
  ]
}

lit_decrypt

Decrypt a Lit Protocol-encrypted evidence bundle using a Lit auth signature. Returns the decrypted bundle payload.

Parameters2

bundleId	string	required	Evidence bundle ID (must be Lit-encrypted)
authSig	object	required	Lit auth signature object with sig, derivedVia, signedMessage, and address fields

Raw schema

{
  "type": "object",
  "properties": {
    "bundleId": {
      "type": "string",
      "description": "Evidence bundle ID (must be Lit-encrypted)"
    },
    "authSig": {
      "type": "object",
      "description": "Lit auth signature object with sig, derivedVia, signedMessage, and address fields",
      "properties": {
        "sig": {
          "type": "string"
        },
        "derivedVia": {
          "type": "string"
        },
        "signedMessage": {
          "type": "string"
        },
        "address": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "bundleId",
    "authSig"
  ]
}

verify_evidence_zk

Verify a ZK proof by its proof ID. Checks the proof against its verification key and public inputs.

Parameters1

proofId

string

required

ID of the ZK proof to verify

Raw schema

{
  "type": "object",
  "properties": {
    "proofId": {
      "type": "string",
      "description": "ID of the ZK proof to verify"
    }
  },
  "required": [
    "proofId"
  ]
}

commit_evidence

Create a Merkle commitment for an evidence bundle hash. Used as the first step in ZK proof generation for Tier 3 assurance.

Parameters1

bundleHash

string

required

SHA-256 hash of the evidence bundle

Raw schema

{
  "type": "object",
  "properties": {
    "bundleHash": {
      "type": "string",
      "description": "SHA-256 hash of the evidence bundle"
    }
  },
  "required": [
    "bundleHash"
  ]
}

get_telemetry_stats

Get aggregate pipeline telemetry statistics including phase timings, success rates, and throughput metrics across all jobs.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_active_telemetry

List currently active jobs with their current pipeline phase and telemetry status.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_job_telemetry

Get full event timeline for a specific job — all pipeline phase transitions with timings and metadata.

Parameters1

jobId

string

required

Job ID to get pipeline timeline for

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Job ID to get pipeline timeline for"
    }
  },
  "required": [
    "jobId"
  ]
}

get_telemetry_logs

Query structured logs with filters for level, source, jobId, kernelId, time range, and full-text search.

Parameters8

level	string	optional	Filter by log level
source	string	optional	Filter by source module
jobId	string	optional	Filter by job ID
kernelId	string	optional	Filter by kernel ID
search	string	optional	Full-text search query
after	string	optional	Return logs after this ISO timestamp
before	string	optional	Return logs before this ISO timestamp
limit	number	optional	Max entries to return (default 200)

Raw schema

{
  "type": "object",
  "properties": {
    "level": {
      "type": "string",
      "enum": [
        "debug",
        "info",
        "warn",
        "error"
      ],
      "description": "Filter by log level"
    },
    "source": {
      "type": "string",
      "description": "Filter by source module"
    },
    "jobId": {
      "type": "string",
      "description": "Filter by job ID"
    },
    "kernelId": {
      "type": "string",
      "description": "Filter by kernel ID"
    },
    "search": {
      "type": "string",
      "description": "Full-text search query"
    },
    "after": {
      "type": "string",
      "description": "Return logs after this ISO timestamp"
    },
    "before": {
      "type": "string",
      "description": "Return logs before this ISO timestamp"
    },
    "limit": {
      "type": "number",
      "description": "Max entries to return (default 200)"
    }
  },
  "required": []
}

emit_telemetry

Manually emit a telemetry event for a job pipeline phase. Used by kernels and agents to report execution progress.

Parameters7

jobId	string	required	Job ID
phase	string	required	Pipeline phase name (e.g. intake, binding, execution, evidence, settlement)
status	string	required	Phase status
duration_ms	number	optional	Phase duration in milliseconds
level	string	optional	Log level for this event
source	string	optional	Source module or component
metadata	object	optional	Additional event metadata

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Job ID"
    },
    "phase": {
      "type": "string",
      "description": "Pipeline phase name (e.g. intake, binding, execution, evidence, settlement)"
    },
    "status": {
      "type": "string",
      "enum": [
        "started",
        "completed",
        "failed",
        "skipped"
      ],
      "description": "Phase status"
    },
    "duration_ms": {
      "type": "number",
      "description": "Phase duration in milliseconds"
    },
    "level": {
      "type": "string",
      "enum": [
        "info",
        "warn",
        "error",
        "debug"
      ],
      "description": "Log level for this event"
    },
    "source": {
      "type": "string",
      "description": "Source module or component"
    },
    "metadata": {
      "type": "object",
      "description": "Additional event metadata"
    }
  },
  "required": [
    "jobId",
    "phase",
    "status"
  ]
}

submit_for_human_verification

Submit an evidence bundle for human verification. Selects a panel of verifiers from the network and returns assigned verifier IDs.

Parameters5

bundleHash	string	required	SHA-256 hash of the evidence bundle
photoRef	string	required	Reference to the photo evidence (CID or URL)
referenceRef	string	required	Reference to the reference/spec document
comparisonScore	number	optional	Pre-computed comparison score 0-1 (optional)
verifierCount	number	optional	Number of verifiers to assign (default 5)

Raw schema

{
  "type": "object",
  "properties": {
    "bundleHash": {
      "type": "string",
      "description": "SHA-256 hash of the evidence bundle"
    },
    "photoRef": {
      "type": "string",
      "description": "Reference to the photo evidence (CID or URL)"
    },
    "referenceRef": {
      "type": "string",
      "description": "Reference to the reference/spec document"
    },
    "comparisonScore": {
      "type": "number",
      "description": "Pre-computed comparison score 0-1 (optional)"
    },
    "verifierCount": {
      "type": "number",
      "description": "Number of verifiers to assign (default 5)"
    }
  },
  "required": [
    "bundleHash",
    "photoRef",
    "referenceRef"
  ]
}

get_verification_assignments

Get pending verification assignments for a verifier node. Returns requests this verifier has been assigned but not yet responded to.

Parameters1

verifierId

string

required

Verifier node ID

Raw schema

{
  "type": "object",
  "properties": {
    "verifierId": {
      "type": "string",
      "description": "Verifier node ID"
    }
  },
  "required": [
    "verifierId"
  ]
}

get_verification_status

Get verification status for a request. Returns vote tally, consensus state, dispute list, and pending response count.

Parameters1

requestId

string

required

Verification request ID (hvreq_...)

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Verification request ID (hvreq_...)"
    }
  },
  "required": [
    "requestId"
  ]
}

respond_to_verification

Submit a verifier's verdict for a verification request. Returns consensus state after this vote.

Parameters5

requestId	string	required	Verification request ID (hvreq_...)
verifierId	string	required	Verifier node ID
verdict	string	required	Verifier's verdict
notes	string	optional	Optional notes explaining the verdict
signature	string	required	Cryptographic signature of the verdict

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Verification request ID (hvreq_...)"
    },
    "verifierId": {
      "type": "string",
      "description": "Verifier node ID"
    },
    "verdict": {
      "type": "string",
      "enum": [
        "match",
        "no_match",
        "inconclusive"
      ],
      "description": "Verifier's verdict"
    },
    "notes": {
      "type": "string",
      "description": "Optional notes explaining the verdict"
    },
    "signature": {
      "type": "string",
      "description": "Cryptographic signature of the verdict"
    }
  },
  "required": [
    "requestId",
    "verifierId",
    "verdict",
    "signature"
  ]
}

dispute_verification

File a dispute against the consensus verdict. Only verifiers who submitted a response can dispute. Requires additional evidence CID.

Parameters4

requestId	string	required	Verification request ID (hvreq_...)
disputerId	string	required	Verifier node ID filing the dispute
reason	string	required	Reason for disputing the consensus
evidenceCid	string	required	IPFS CID of the counter-evidence

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Verification request ID (hvreq_...)"
    },
    "disputerId": {
      "type": "string",
      "description": "Verifier node ID filing the dispute"
    },
    "reason": {
      "type": "string",
      "description": "Reason for disputing the consensus"
    },
    "evidenceCid": {
      "type": "string",
      "description": "IPFS CID of the counter-evidence"
    }
  },
  "required": [
    "requestId",
    "disputerId",
    "reason",
    "evidenceCid"
  ]
}

register_capability_ip

Register a capability as a Story Protocol IP Asset. Returns an ipId and NFT token. The designer earns royalties whenever this capability is used.

Parameters5

capability	object	required	Capability object
designerAddress	string	required	EVM address of the capability designer
designerName	string	required	Display name of the designer
commercialRevShare	number	optional	Revenue share percentage for commercial use (0-100)
ipfsCid	string	optional	IPFS CID of the capability spec document (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "capability": {
      "type": "object",
      "description": "Capability object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "kernelId": {
          "type": "string"
        },
        "description": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "type",
        "kernelId"
      ]
    },
    "designerAddress": {
      "type": "string",
      "description": "EVM address of the capability designer"
    },
    "designerName": {
      "type": "string",
      "description": "Display name of the designer"
    },
    "commercialRevShare": {
      "type": "number",
      "description": "Revenue share percentage for commercial use (0-100)"
    },
    "ipfsCid": {
      "type": "string",
      "description": "IPFS CID of the capability spec document (optional)"
    }
  },
  "required": [
    "capability",
    "designerAddress",
    "designerName"
  ]
}

register_job_evidence_ip

Register job evidence as a derivative IP asset on Story Protocol, linking it to the parent capability's IP. Operators earn royalties from derivative use.

Parameters6

parentIpId	string	required	IP ID of the parent capability
jobId	string	required	Job ID whose evidence is being registered
evidenceBundleHash	string	required	Hash of the evidence bundle
operatorAddress	string	required	EVM address of the operator
operatorName	string	required	Display name of the operator
ipfsCid	string	optional	IPFS CID of the evidence bundle (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "parentIpId": {
      "type": "string",
      "description": "IP ID of the parent capability"
    },
    "jobId": {
      "type": "string",
      "description": "Job ID whose evidence is being registered"
    },
    "evidenceBundleHash": {
      "type": "string",
      "description": "Hash of the evidence bundle"
    },
    "operatorAddress": {
      "type": "string",
      "description": "EVM address of the operator"
    },
    "operatorName": {
      "type": "string",
      "description": "Display name of the operator"
    },
    "ipfsCid": {
      "type": "string",
      "description": "IPFS CID of the evidence bundle (optional)"
    }
  },
  "required": [
    "parentIpId",
    "jobId",
    "evidenceBundleHash",
    "operatorAddress",
    "operatorName"
  ]
}

distribute_royalties

Set revenue splits for an IP asset among stakeholders (designer, operator, verifier, assembler, curator). Splits must sum to 100.

Parameters2

ipId	string	required	IP asset ID
splits	array	required	Revenue splits — must sum to 100

Raw schema

{
  "type": "object",
  "properties": {
    "ipId": {
      "type": "string",
      "description": "IP asset ID"
    },
    "splits": {
      "type": "array",
      "description": "Revenue splits — must sum to 100",
      "items": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "Recipient EVM address"
          },
          "role": {
            "type": "string",
            "enum": [
              "designer",
              "operator",
              "verifier",
              "assembler",
              "curator"
            ]
          },
          "percentage": {
            "type": "number",
            "description": "Percentage share (0-100)"
          },
          "label": {
            "type": "string",
            "description": "Human-readable label"
          }
        },
        "required": [
          "address",
          "role",
          "percentage",
          "label"
        ]
      }
    }
  },
  "required": [
    "ipId",
    "splits"
  ]
}

pay_ip_royalty

Pay royalties to an IP asset vault. The payer sends tokens that flow to stakeholders via the royalty splits.

Parameters3

ipId	string	required	IP asset ID
amount	string	required	Amount to pay in wei (as string)
payerAddress	string	required	EVM address of the payer

Raw schema

{
  "type": "object",
  "properties": {
    "ipId": {
      "type": "string",
      "description": "IP asset ID"
    },
    "amount": {
      "type": "string",
      "description": "Amount to pay in wei (as string)"
    },
    "payerAddress": {
      "type": "string",
      "description": "EVM address of the payer"
    }
  },
  "required": [
    "ipId",
    "amount",
    "payerAddress"
  ]
}

claim_ip_revenue

Claim earned revenue from an IP asset vault. Returns the claimed amount and transaction hash.

Parameters2

ipId	string	required	IP asset ID
tokenIds	array	optional	Specific royalty token IDs to claim (optional — claims all if omitted)

Raw schema

{
  "type": "object",
  "properties": {
    "ipId": {
      "type": "string",
      "description": "IP asset ID"
    },
    "tokenIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Specific royalty token IDs to claim (optional — claims all if omitted)"
    }
  },
  "required": [
    "ipId"
  ]
}

get_ip_revenue

Get a revenue snapshot for an IP asset — total earned, pending claims, and recent payments.

Parameters1

ipId

string

required

IP asset ID

Raw schema

{
  "type": "object",
  "properties": {
    "ipId": {
      "type": "string",
      "description": "IP asset ID"
    }
  },
  "required": [
    "ipId"
  ]
}

get_ip_lineage

Get the full IP lineage chain for an asset — parent capabilities and all derivative job registrations.

Parameters1

ipId

string

required

IP asset ID

Raw schema

{
  "type": "object",
  "properties": {
    "ipId": {
      "type": "string",
      "description": "IP asset ID"
    }
  },
  "required": [
    "ipId"
  ]
}

get_capability_ip

Get the Story Protocol IP registration for a capability by its capability ID.

Parameters1

capabilityId

string

required

Capability ID to look up IP registration for

Raw schema

{
  "type": "object",
  "properties": {
    "capabilityId": {
      "type": "string",
      "description": "Capability ID to look up IP registration for"
    }
  },
  "required": [
    "capabilityId"
  ]
}

raise_ip_dispute

Raise a Story Protocol IP dispute against an asset. Provide evidence hash and reason.

Parameters3

ipId	string	required	IP asset ID to dispute
evidenceHash	string	required	Hash of the dispute evidence
reason	string	required	Reason for the dispute

Raw schema

{
  "type": "object",
  "properties": {
    "ipId": {
      "type": "string",
      "description": "IP asset ID to dispute"
    },
    "evidenceHash": {
      "type": "string",
      "description": "Hash of the dispute evidence"
    },
    "reason": {
      "type": "string",
      "description": "Reason for the dispute"
    }
  },
  "required": [
    "ipId",
    "evidenceHash",
    "reason"
  ]
}

list_protocols

List protocol templates in the library. Filter by tags, required capabilities, search query, or status.

Parameters4

tags	string	optional	Comma-separated tag filter (e.g. 'biotech,protein')
capabilities	string	optional	Comma-separated required capability filter (e.g. 'hplc,centrifuge')
search	string	optional	Full-text search query
status	string	optional	Filter by template status

Raw schema

{
  "type": "object",
  "properties": {
    "tags": {
      "type": "string",
      "description": "Comma-separated tag filter (e.g. 'biotech,protein')"
    },
    "capabilities": {
      "type": "string",
      "description": "Comma-separated required capability filter (e.g. 'hplc,centrifuge')"
    },
    "search": {
      "type": "string",
      "description": "Full-text search query"
    },
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "published",
        "archived"
      ],
      "description": "Filter by template status"
    }
  },
  "required": []
}

get_protocol

Get protocol template details by ID. Returns steps, transfers, parameters, and metadata.

Parameters1

string

required

Protocol template ID

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Protocol template ID"
    }
  },
  "required": [
    "id"
  ]
}

create_protocol

Create a new protocol template draft. Returns the new template ID.

Parameters7

name	string	required	Protocol name
description	string	optional	Protocol description
steps	array	optional	Array of protocol step objects
transfers	array	optional	Array of transfer objects between steps
parameters	array	optional	Array of parameter definitions
tags	array	optional	Tags for discovery
requiredCapabilities	array	optional	Required capability types

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Protocol name"
    },
    "description": {
      "type": "string",
      "description": "Protocol description"
    },
    "steps": {
      "type": "array",
      "description": "Array of protocol step objects"
    },
    "transfers": {
      "type": "array",
      "description": "Array of transfer objects between steps"
    },
    "parameters": {
      "type": "array",
      "description": "Array of parameter definitions"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tags for discovery"
    },
    "requiredCapabilities": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Required capability types"
    }
  },
  "required": [
    "name"
  ]
}

update_protocol

Update an existing protocol template (must be in draft status). Returns updated name and version.

Parameters6

id	string	required	Protocol template ID
name	string	optional	Updated name
description	string	optional	Updated description
version	string	optional	New version string (semver)
steps	array	optional	Updated steps array
parameters	array	optional	Updated parameters array

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Protocol template ID"
    },
    "name": {
      "type": "string",
      "description": "Updated name"
    },
    "description": {
      "type": "string",
      "description": "Updated description"
    },
    "version": {
      "type": "string",
      "description": "New version string (semver)"
    },
    "steps": {
      "type": "array",
      "description": "Updated steps array"
    },
    "parameters": {
      "type": "array",
      "description": "Updated parameters array"
    }
  },
  "required": [
    "id"
  ]
}

publish_protocol

Publish a draft protocol template, making it visible in the protocol library for others to discover and use.

Parameters1

string

required

Protocol template ID to publish

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Protocol template ID to publish"
    }
  },
  "required": [
    "id"
  ]
}

fork_protocol

Fork a protocol template to create your own version with parameter overrides. Returns the new fork ID.

Parameters3

id	string	required	Protocol template ID to fork
name	string	optional	Name for the forked protocol
parameterOverrides	object	optional	Parameter values to override from the source template

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Protocol template ID to fork"
    },
    "name": {
      "type": "string",
      "description": "Name for the forked protocol"
    },
    "parameterOverrides": {
      "type": "object",
      "description": "Parameter values to override from the source template"
    }
  },
  "required": [
    "id"
  ]
}

get_protocol_forks

List all forks of a protocol template. Shows who forked it and what parameters they changed.

Parameters1

string

required

Protocol template ID

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Protocol template ID"
    }
  },
  "required": [
    "id"
  ]
}

validate_protocol

Validate a protocol template against a specific kernel — checks capability availability, transfer compatibility, and automation level feasibility.

Parameters2

id	string	required	Protocol template ID
kernelId	string	optional	Kernel ID to validate against (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Protocol template ID"
    },
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to validate against (optional)"
    }
  },
  "required": [
    "id"
  ]
}

list_protocol_runs

List protocol runs. Filter by status or kernelId.

Parameters2

status	string	optional	Filter by run status
kernelId	string	optional	Filter by kernel ID

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "binding",
        "ready",
        "running",
        "paused",
        "completed",
        "cancelled",
        "failed"
      ],
      "description": "Filter by run status"
    },
    "kernelId": {
      "type": "string",
      "description": "Filter by kernel ID"
    }
  },
  "required": []
}

get_protocol_run

Get protocol run status including step progress, transfer status, current phase, and evidence hashes.

Parameters1

runId

string

required

Protocol run ID

Raw schema

{
  "type": "object",
  "properties": {
    "runId": {
      "type": "string",
      "description": "Protocol run ID"
    }
  },
  "required": [
    "runId"
  ]
}

create_protocol_run

Instantiate a protocol template as a run on a specific kernel with given parameter values.

Parameters4

id	string	required	Protocol template ID
kernelId	string	optional	Kernel ID to run the protocol on
parameterValues	object	optional	Runtime parameter values (overrides template defaults)
sampleIds	array	optional	Sample IDs being processed in this run

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Protocol template ID"
    },
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to run the protocol on"
    },
    "parameterValues": {
      "type": "object",
      "description": "Runtime parameter values (overrides template defaults)"
    },
    "sampleIds": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Sample IDs being processed in this run"
    }
  },
  "required": [
    "id"
  ]
}

start_protocol_run

Start execution of a protocol run that is in 'ready' or 'binding' state.

Parameters1

runId

string

required

Protocol run ID to start

Raw schema

{
  "type": "object",
  "properties": {
    "runId": {
      "type": "string",
      "description": "Protocol run ID to start"
    }
  },
  "required": [
    "runId"
  ]
}

pause_protocol_run

Pause a running protocol run. Use resume_protocol_run to continue.

Parameters1

runId

string

required

Protocol run ID to pause

Raw schema

{
  "type": "object",
  "properties": {
    "runId": {
      "type": "string",
      "description": "Protocol run ID to pause"
    }
  },
  "required": [
    "runId"
  ]
}

resume_protocol_run

Resume a paused protocol run from where it stopped.

Parameters1

runId

string

required

Protocol run ID to resume

Raw schema

{
  "type": "object",
  "properties": {
    "runId": {
      "type": "string",
      "description": "Protocol run ID to resume"
    }
  },
  "required": [
    "runId"
  ]
}

cancel_protocol_run

Cancel a protocol run. Cannot be cancelled once completed or already cancelled.

Parameters1

runId

string

required

Protocol run ID to cancel

Raw schema

{
  "type": "object",
  "properties": {
    "runId": {
      "type": "string",
      "description": "Protocol run ID to cancel"
    }
  },
  "required": [
    "runId"
  ]
}

get_workflows

List active instrument workflows in the orchestrator. Optionally filter by status.

Parameters1

status

string

optional

Filter by workflow status (e.g. running, completed)

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter by workflow status (e.g. running, completed)"
    }
  },
  "required": []
}

get_workflow

Get detailed workflow information including steps, node assignments, and progress.

Parameters1

workflowId

string

required

Workflow ID

Raw schema

{
  "type": "object",
  "properties": {
    "workflowId": {
      "type": "string",
      "description": "Workflow ID"
    }
  },
  "required": [
    "workflowId"
  ]
}

get_transfer_graphs

Get resource transfer graphs showing instrument topology, transfer edges, and mechanisms for all kernels.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

list_automation_status

List automation status for all instrument transfer pairs. Shows current automation level, episode count, and training readiness. Filter by kernelId.

Parameters1

kernelId

string

optional

Filter by kernel ID

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Filter by kernel ID"
    }
  },
  "required": []
}

get_automation_status

Get automation status for a specific instrument-to-instrument transfer pair.

Parameters2

fromNodeId	string	required	Source instrument node ID
toNodeId	string	required	Destination instrument node ID

Raw schema

{
  "type": "object",
  "properties": {
    "fromNodeId": {
      "type": "string",
      "description": "Source instrument node ID"
    },
    "toNodeId": {
      "type": "string",
      "description": "Destination instrument node ID"
    }
  },
  "required": [
    "fromNodeId",
    "toNodeId"
  ]
}

record_episode

Record a transfer episode for a node pair. Increments episode count toward VLA training threshold.

Parameters4

fromNodeId	string	required	Source instrument node ID
toNodeId	string	required	Destination instrument node ID
episodeId	string	optional	Episode ID (optional)
success	boolean	optional	Whether the episode succeeded

Raw schema

{
  "type": "object",
  "properties": {
    "fromNodeId": {
      "type": "string",
      "description": "Source instrument node ID"
    },
    "toNodeId": {
      "type": "string",
      "description": "Destination instrument node ID"
    },
    "episodeId": {
      "type": "string",
      "description": "Episode ID (optional)"
    },
    "success": {
      "type": "boolean",
      "description": "Whether the episode succeeded"
    }
  },
  "required": [
    "fromNodeId",
    "toNodeId"
  ]
}

advance_automation

Advance the automation level for a transfer pair (manual → teleoperated → pilot_operated → vla_assisted → fully_autonomous). Requires sufficient training episodes.

Parameters2

fromNodeId	string	required	Source instrument node ID
toNodeId	string	required	Destination instrument node ID

Raw schema

{
  "type": "object",
  "properties": {
    "fromNodeId": {
      "type": "string",
      "description": "Source instrument node ID"
    },
    "toNodeId": {
      "type": "string",
      "description": "Destination instrument node ID"
    }
  },
  "required": [
    "fromNodeId",
    "toNodeId"
  ]
}

list_transfer_agents

List all transfer agents (robots and human operators) available for instrument-to-instrument transfers.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_logistics_overview

Logistics hub overview: active shipments, pending installations, and upcoming bookings.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_shipments

List equipment shipments with tracking status. Optionally filter by status.

Parameters1

status

string

optional

Filter by shipment status (in_transit, delivered, pickup_scheduled, etc.)

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter by shipment status (in_transit, delivered, pickup_scheduled, etc.)"
    }
  },
  "required": []
}

create_shipment

Create a new equipment shipment with origin, destination, package details, and provider.

Parameters5

equipmentDescription	string	required	Description of equipment being shipped
providerId	string	optional	Logistics provider ID
origin	object	optional	Origin location with label, address, geo coordinates
destination	object	optional	Destination location with label, address, geo coordinates
package	object	optional	Package details (weightKg, dimensions, fragile, etc.)

Raw schema

{
  "type": "object",
  "properties": {
    "equipmentDescription": {
      "type": "string",
      "description": "Description of equipment being shipped"
    },
    "providerId": {
      "type": "string",
      "description": "Logistics provider ID"
    },
    "origin": {
      "type": "object",
      "description": "Origin location with label, address, geo coordinates"
    },
    "destination": {
      "type": "object",
      "description": "Destination location with label, address, geo coordinates"
    },
    "package": {
      "type": "object",
      "description": "Package details (weightKg, dimensions, fragile, etc.)"
    }
  },
  "required": [
    "equipmentDescription"
  ]
}

get_shipment_quote

Get shipping quotes from logistics providers based on origin, destination, weight, and priority.

Parameters4

originZip	string	optional	Origin ZIP code
destinationZip	string	optional	Destination ZIP code
weightKg	number	optional	Package weight in kg
priority	string	optional	Shipping priority level

Raw schema

{
  "type": "object",
  "properties": {
    "originZip": {
      "type": "string",
      "description": "Origin ZIP code"
    },
    "destinationZip": {
      "type": "string",
      "description": "Destination ZIP code"
    },
    "weightKg": {
      "type": "number",
      "description": "Package weight in kg"
    },
    "priority": {
      "type": "string",
      "enum": [
        "standard",
        "expedited",
        "rush"
      ],
      "description": "Shipping priority level"
    }
  },
  "required": []
}

get_installations

List equipment installation orders with step progress and status.

Parameters1

status

string

optional

Filter by installation status (draft, scheduled, in_progress, completed)

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter by installation status (draft, scheduled, in_progress, completed)"
    }
  },
  "required": []
}

get_space_bookings

List space bookings for hosting equipment. Optionally filter by status or space.

Parameters2

status	string	optional	Filter by booking status
spaceId	string	optional	Filter by space ID

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter by booking status"
    },
    "spaceId": {
      "type": "string",
      "description": "Filter by space ID"
    }
  },
  "required": []
}

search_spaces

Search for lab/workshop hosting spaces. Filter by size, access schedule, and other requirements.

Parameters2

maxSqft	number	optional	Maximum square footage
access	string	optional	Access schedule (24/7, business-hours, all)

Raw schema

{
  "type": "object",
  "properties": {
    "maxSqft": {
      "type": "number",
      "description": "Maximum square footage"
    },
    "access": {
      "type": "string",
      "description": "Access schedule (24/7, business-hours, all)"
    }
  },
  "required": []
}

get_space

Get detailed information about a hosting space including power, amenities, safety features, and pricing.

Parameters1

string

required

Space ID

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Space ID"
    }
  },
  "required": [
    "id"
  ]
}

match_spaces

Find hosting spaces that match specific machine requirements (voltage, area, etc.). Returns scored matches.

Parameters2

voltage	number	optional	Required voltage (e.g. 208, 480)
minArea	number	optional	Minimum floor area in square feet

Raw schema

{
  "type": "object",
  "properties": {
    "voltage": {
      "type": "number",
      "description": "Required voltage (e.g. 208, 480)"
    },
    "minArea": {
      "type": "number",
      "description": "Minimum floor area in square feet"
    }
  },
  "required": []
}

get_marketplace_overview

Equipment marketplace overview with demand/supply metrics across all capability types.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_equipment_classes

List equipment classes (FDM printers, CNC mills, etc.) with market snapshot data including utilization, demand, and pricing.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_demand_supply

Get network-wide demand vs supply timeline data for capacity planning and market analysis.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

calculate_roi

Calculate ROI projection for onboarding equipment. Returns month-by-month revenue, cost, and break-even analysis.

Parameters3

monthlyCost	number	optional	Monthly operating cost in USD
avgJobValue	number	optional	Average revenue per job in USD
utilization	number	optional	Expected utilization percentage (0-100)

Raw schema

{
  "type": "object",
  "properties": {
    "monthlyCost": {
      "type": "number",
      "description": "Monthly operating cost in USD"
    },
    "avgJobValue": {
      "type": "number",
      "description": "Average revenue per job in USD"
    },
    "utilization": {
      "type": "number",
      "description": "Expected utilization percentage (0-100)"
    }
  },
  "required": []
}

get_operator_dashboard

Operator dashboard overview: machines, earnings summary, and maintenance alerts.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_operator_machines

List all machines registered under the operator account with utilization and uptime stats.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_operator_earnings

Get operator earnings breakdown over a time period. Includes daily earnings and cumulative totals.

Parameters1

period

string

optional

Time period for earnings data

Raw schema

{
  "type": "object",
  "properties": {
    "period": {
      "type": "string",
      "enum": [
        "7d",
        "30d",
        "90d",
        "1y"
      ],
      "description": "Time period for earnings data"
    }
  },
  "required": []
}

get_operator_certs

List operator certifications (OSHA, safety training, PCC network certs) with validity status.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_sensor_channels

List all registered sensor channels across kernels. Returns channel descriptors with units and ranges.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_kernel_sensors

Get sensor channels for a specific kernel. Returns live channel descriptors.

Parameters1

kernelId

string

required

Kernel ID to get sensors for

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to get sensors for"
    }
  },
  "required": [
    "kernelId"
  ]
}

get_settlement_status

Get settlement pipeline status including pending operations count, total value queued, and smart account address.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_settlement_epochs

Get settlement epoch history showing past batch settlements with timing and operation counts.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_depin_stats

DePIN treasury, soulbound capability certificates, and current reward epoch stats.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

mint_certificate

Mint a soulbound capability certificate (cNFT via Metaplex Core) for a kernel. Proves a verified capability on-chain as an immutable credential. Step 5 of onboarding.

Parameters4

kernelDid	string	required	DID of the kernel (e.g. did:pcc:kernel:biolab-01)
capabilityType	string	required	Capability type (e.g. fdm, cnc-3axis, hplc)
assuranceTier	number	optional	Assurance tier (0-3)
metadata	object	optional	Additional metadata (tolerances, materials, calibration proof CID)

Raw schema

{
  "type": "object",
  "properties": {
    "kernelDid": {
      "type": "string",
      "description": "DID of the kernel (e.g. did:pcc:kernel:biolab-01)"
    },
    "capabilityType": {
      "type": "string",
      "description": "Capability type (e.g. fdm, cnc-3axis, hplc)"
    },
    "assuranceTier": {
      "type": "number",
      "description": "Assurance tier (0-3)"
    },
    "metadata": {
      "type": "object",
      "description": "Additional metadata (tolerances, materials, calibration proof CID)"
    }
  },
  "required": [
    "kernelDid",
    "capabilityType"
  ]
}

onboard_machine

Parameters6

name	string	required	Machine name
category	string	required	Machine category (e.g. fdm, cnc, laser-cut, hplc)
manufacturer	string	optional	Manufacturer name
model	string	optional	Model identifier
description	string	optional	Machine description
capabilities	array	optional	Array of capability objects

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Machine name"
    },
    "category": {
      "type": "string",
      "description": "Machine category (e.g. fdm, cnc, laser-cut, hplc)"
    },
    "manufacturer": {
      "type": "string",
      "description": "Manufacturer name"
    },
    "model": {
      "type": "string",
      "description": "Model identifier"
    },
    "description": {
      "type": "string",
      "description": "Machine description"
    },
    "capabilities": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Array of capability objects"
    }
  },
  "required": [
    "name",
    "category"
  ]
}

analyze_machine_docs

AI analysis of machine documentation. Upload docs to get suggested capabilities, extracted specs, materials, and tolerances.

Parameters1

document

string

optional

Document content or reference to analyze

Raw schema

{
  "type": "object",
  "properties": {
    "document": {
      "type": "string",
      "description": "Document content or reference to analyze"
    }
  },
  "required": []
}

redeem_invite

One-click agent onboarding with an invite code. Provisions wallet, identity, LLM access, and PCC tools in a single call.

Parameters4

inviteCode	string	required	Invite code to redeem
email	string	required	Email address for the account
password	string	required	Password for the account
name	string	optional	Display name (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "inviteCode": {
      "type": "string",
      "description": "Invite code to redeem"
    },
    "email": {
      "type": "string",
      "description": "Email address for the account"
    },
    "password": {
      "type": "string",
      "description": "Password for the account"
    },
    "name": {
      "type": "string",
      "description": "Display name (optional)"
    }
  },
  "required": [
    "inviteCode",
    "email",
    "password"
  ]
}

check_invite

Validate an invite code before redeeming it. Returns whether the code is valid and what it includes.

Parameters1

code

string

required

Invite code to check

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Invite code to check"
    }
  },
  "required": [
    "code"
  ]
}

list_batches

List active and completed settlement batches.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

list_evidence

List encrypted evidence bundles stored in the gateway.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

submit_demand

Signal that you want a capability that doesn't exist on the network yet. Creates a demand signal and may auto-create a bounty if enough demand accumulates.

Parameters6

requesterId	string	required	ID of the requester
capabilityType	string	required	Type of capability wanted (e.g. electron-beam-welding, cryo-em)
description	string	required	Description of what you need
estimatedJobValue	number	optional	Estimated payment per job in USD
estimatedFrequency	string	optional	How often you would use this capability
assuranceTier	number	optional	Required assurance tier (0-3)

Raw schema

{
  "type": "object",
  "properties": {
    "requesterId": {
      "type": "string",
      "description": "ID of the requester"
    },
    "capabilityType": {
      "type": "string",
      "description": "Type of capability wanted (e.g. electron-beam-welding, cryo-em)"
    },
    "description": {
      "type": "string",
      "description": "Description of what you need"
    },
    "estimatedJobValue": {
      "type": "number",
      "description": "Estimated payment per job in USD"
    },
    "estimatedFrequency": {
      "type": "string",
      "enum": [
        "one-time",
        "weekly",
        "monthly",
        "daily"
      ],
      "description": "How often you would use this capability"
    },
    "assuranceTier": {
      "type": "number",
      "description": "Required assurance tier (0-3)"
    }
  },
  "required": [
    "requesterId",
    "capabilityType",
    "description"
  ]
}

list_bounties

List open bounties for capabilities the network needs. Operators can claim these to earn rewards by onboarding new capabilities.

Parameters2

status	string	optional	Filter by bounty status
capabilityType	string	optional	Filter by capability type

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "open",
        "claimed",
        "verified",
        "paid",
        "expired"
      ],
      "description": "Filter by bounty status"
    },
    "capabilityType": {
      "type": "string",
      "description": "Filter by capability type"
    }
  },
  "required": []
}

claim_bounty

Claim a bounty to onboard a new capability. The operator commits to registering the capability and completing verification.

Parameters2

bountyId	string	required	ID of the bounty to claim
operatorId	string	required	ID of the operator claiming the bounty

Raw schema

{
  "type": "object",
  "properties": {
    "bountyId": {
      "type": "string",
      "description": "ID of the bounty to claim"
    },
    "operatorId": {
      "type": "string",
      "description": "ID of the operator claiming the bounty"
    }
  },
  "required": [
    "bountyId",
    "operatorId"
  ]
}

verify_bounty

Verify bounty completion by scoring the delivered capability against requirements.

Parameters3

bountyId	string	required	Bounty ID to verify
jobId	string	required	Job ID that fulfilled the bounty
score	number	required	Verification score (0-1)

Raw schema

{
  "type": "object",
  "properties": {
    "bountyId": {
      "type": "string",
      "description": "Bounty ID to verify"
    },
    "jobId": {
      "type": "string",
      "description": "Job ID that fulfilled the bounty"
    },
    "score": {
      "type": "number",
      "description": "Verification score (0-1)"
    }
  },
  "required": [
    "bountyId",
    "jobId",
    "score"
  ]
}

get_top_demand

Get top demand signals aggregated by capability type. Shows which capabilities are most wanted on the network.

Parameters1

limit

number

optional

Number of top demand entries to return (default 10)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Number of top demand entries to return (default 10)"
    }
  },
  "required": []
}

get_bounty_leaderboard

Get the bounty hunter leaderboard showing top operators by bounties claimed and verified.

Parameters1

limit

number

optional

Number of entries to return (default 10)

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Number of entries to return (default 10)"
    }
  },
  "required": []
}

create_investment_pool

Create an investment pool for a capability bounty. Stakers earn future protocol fees when the capability goes live.

Parameters4

capabilityType	string	required	Type of capability to invest in (e.g. cnc-milling, sla-printing)
description	string	required	Description of the capability pool
targetAmount	number	optional	Funding target amount
currency	string	optional	Currency for the pool

Raw schema

{
  "type": "object",
  "properties": {
    "capabilityType": {
      "type": "string",
      "description": "Type of capability to invest in (e.g. cnc-milling, sla-printing)"
    },
    "description": {
      "type": "string",
      "description": "Description of the capability pool"
    },
    "targetAmount": {
      "type": "number",
      "description": "Funding target amount"
    },
    "currency": {
      "type": "string",
      "enum": [
        "USDC",
        "CREDITS"
      ],
      "description": "Currency for the pool"
    }
  },
  "required": [
    "capabilityType",
    "description"
  ]
}

stake_in_pool

Stake USDC or credits into a capability investment pool.

Parameters3

poolId	string	required	Investment pool ID
staker	string	required	Address or DID of the staker
amount	number	required	Amount to stake

Raw schema

{
  "type": "object",
  "properties": {
    "poolId": {
      "type": "string",
      "description": "Investment pool ID"
    },
    "staker": {
      "type": "string",
      "description": "Address or DID of the staker"
    },
    "amount": {
      "type": "number",
      "description": "Amount to stake"
    }
  },
  "required": [
    "poolId",
    "staker",
    "amount"
  ]
}

get_pool_earnings

Check earnings from capability investment pools for a staker address.

Parameters1

staker

string

required

Address or DID of the staker

Raw schema

{
  "type": "object",
  "properties": {
    "staker": {
      "type": "string",
      "description": "Address or DID of the staker"
    }
  },
  "required": [
    "staker"
  ]
}

get_pool

Get details of a specific investment pool including stakes, status, and revenue share terms.

Parameters1

poolId

string

required

Investment pool ID

Raw schema

{
  "type": "object",
  "properties": {
    "poolId": {
      "type": "string",
      "description": "Investment pool ID"
    }
  },
  "required": [
    "poolId"
  ]
}

list_pools

List all investment pools. Optionally filter by status or capability type.

Parameters2

status	string	optional	Filter by pool status
capabilityType	string	optional	Filter by capability type

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "open",
        "funded",
        "active",
        "sunset",
        "cancelled"
      ],
      "description": "Filter by pool status"
    },
    "capabilityType": {
      "type": "string",
      "description": "Filter by capability type"
    }
  },
  "required": []
}

close_pool

Close an investment pool to new stakes. Pool enters sunset phase.

Parameters1

poolId

string

required

Pool ID to close

Raw schema

{
  "type": "object",
  "properties": {
    "poolId": {
      "type": "string",
      "description": "Pool ID to close"
    }
  },
  "required": [
    "poolId"
  ]
}

claim_pool

Operator claims an investment pool reward after capability verification.

Parameters2

poolId	string	required	Pool ID to claim
operatorId	string	required	Operator ID making the claim

Raw schema

{
  "type": "object",
  "properties": {
    "poolId": {
      "type": "string",
      "description": "Pool ID to claim"
    },
    "operatorId": {
      "type": "string",
      "description": "Operator ID making the claim"
    }
  },
  "required": [
    "poolId",
    "operatorId"
  ]
}

convert_bounty_to_pool

Convert an existing bounty into an investment pool. Allows community staking toward the bounty's capability.

Parameters1

bountyId

string

required

Bounty ID to convert to a pool

Raw schema

{
  "type": "object",
  "properties": {
    "bountyId": {
      "type": "string",
      "description": "Bounty ID to convert to a pool"
    }
  },
  "required": [
    "bountyId"
  ]
}

get_subnet_status

Get Bittensor verification subnet health, agent bridge status, and network connectivity.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_subnet_miners

List verification subnet miners on the Bittensor network. Returns miner addresses, scores, and leaderboard positions.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

list_conversations

List agent-to-agent conversations showing topic, participants, message count, and status.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

submit_feedback

Submit a bug report, suggestion, or general feedback about the PCC network.

Parameters3

type	string	optional	Feedback type
message	string	required	Feedback message (max 5000 chars)
page	string	optional	Page or feature the feedback relates to

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "bug",
        "comment",
        "difficulty",
        "suggestion"
      ],
      "description": "Feedback type"
    },
    "message": {
      "type": "string",
      "description": "Feedback message (max 5000 chars)"
    },
    "page": {
      "type": "string",
      "description": "Page or feature the feedback relates to"
    }
  },
  "required": [
    "message"
  ]
}

report_anomaly

Report a detected anomaly — protocol failure, evidence mismatch, stuck job, or suspicious behavior. All agents on the network are notified.

Parameters5

severity	string	required	Anomaly severity
category	string	required	Anomaly category
description	string	required	Human-readable description of what went wrong
targetAgentId	string	optional	Agent or kernel ID being reported (optional)
jobId	string	optional	Related job ID (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "severity": {
      "type": "string",
      "enum": [
        "info",
        "warning",
        "critical"
      ],
      "description": "Anomaly severity"
    },
    "category": {
      "type": "string",
      "enum": [
        "protocol_failure",
        "evidence_mismatch",
        "consensus_failure",
        "timeout",
        "rate_anomaly",
        "trust_violation"
      ],
      "description": "Anomaly category"
    },
    "description": {
      "type": "string",
      "description": "Human-readable description of what went wrong"
    },
    "targetAgentId": {
      "type": "string",
      "description": "Agent or kernel ID being reported (optional)"
    },
    "jobId": {
      "type": "string",
      "description": "Related job ID (optional)"
    }
  },
  "required": [
    "severity",
    "category",
    "description"
  ]
}

get_unresolved_anomalies

List all unresolved anomalies on the network. Filter by severity, category, or target agent.

Parameters3

severity	string	optional	Filter by severity: info, warning, critical
category	string	optional	Filter by category
targetId	string	optional	Filter by target agent/kernel ID

Raw schema

{
  "type": "object",
  "properties": {
    "severity": {
      "type": "string",
      "description": "Filter by severity: info, warning, critical"
    },
    "category": {
      "type": "string",
      "description": "Filter by category"
    },
    "targetId": {
      "type": "string",
      "description": "Filter by target agent/kernel ID"
    }
  },
  "required": []
}

get_agent_anomalies

Get anomalies involving a specific agent, plus their trust impact score.

Parameters1

agentId

string

required

Agent or kernel ID

Raw schema

{
  "type": "object",
  "properties": {
    "agentId": {
      "type": "string",
      "description": "Agent or kernel ID"
    }
  },
  "required": [
    "agentId"
  ]
}

resolve_anomaly

Mark an anomaly as resolved with a resolution note.

Parameters2

anomalyId	string	required	Anomaly ID to resolve
resolution	string	required	How the anomaly was resolved

Raw schema

{
  "type": "object",
  "properties": {
    "anomalyId": {
      "type": "string",
      "description": "Anomaly ID to resolve"
    },
    "resolution": {
      "type": "string",
      "description": "How the anomaly was resolved"
    }
  },
  "required": [
    "anomalyId",
    "resolution"
  ]
}

get_anomaly_stats

Get aggregate anomaly statistics — total, unresolved, by severity, by category.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

report_protocol_failure

Report a protocol failure — when a step in the evidence/escrow/verification pipeline breaks. System may auto-recover.

Parameters6

protocol	string	required	Which protocol failed: evidence_submission, escrow_release, verification_consensus, settlement
errorCode	string	required	Error code
errorMessage	string	required	Error description
involvedAgents	array	required	Agent IDs involved
jobId	string	optional	Related job ID
recoveryAction	string	optional	Suggested recovery

Raw schema

{
  "type": "object",
  "properties": {
    "protocol": {
      "type": "string",
      "description": "Which protocol failed: evidence_submission, escrow_release, verification_consensus, settlement"
    },
    "errorCode": {
      "type": "string",
      "description": "Error code"
    },
    "errorMessage": {
      "type": "string",
      "description": "Error description"
    },
    "involvedAgents": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Agent IDs involved"
    },
    "jobId": {
      "type": "string",
      "description": "Related job ID"
    },
    "recoveryAction": {
      "type": "string",
      "enum": [
        "retry",
        "escalate",
        "rollback",
        "ignore"
      ],
      "description": "Suggested recovery"
    }
  },
  "required": [
    "protocol",
    "errorCode",
    "errorMessage",
    "involvedAgents"
  ]
}

pcc_dht_query

Query the DHT for capabilities matching your requirements. Returns announcements from operators whose equipment matches the type, materials, and price range you specify.

Parameters4

type	string	optional	Capability type to search for (e.g. 'fdm_print', 'liquid-handler', 'cnc-3axis')
materials	array	optional	Materials you need (matches if operator supports ANY of these)
maxPrice	number	optional	Maximum price per job — matches operators whose min price is at or below this
limit	number	optional	Maximum results to return (default 10)

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "Capability type to search for (e.g. 'fdm_print', 'liquid-handler', 'cnc-3axis')"
    },
    "materials": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Materials you need (matches if operator supports ANY of these)"
    },
    "maxPrice": {
      "type": "number",
      "description": "Maximum price per job — matches operators whose min price is at or below this"
    },
    "limit": {
      "type": "number",
      "description": "Maximum results to return (default 10)"
    }
  },
  "required": []
}

pcc_dht_announce

Announce capabilities to the DHT network. Signs the announcement with your node's Ed25519 key and broadcasts to connected peers.

Parameters3

kernelId	string	required	Kernel ID announcing capabilities
capabilities	array	required	Array of capability summaries to announce
ttlSeconds	number	optional	How long the announcement is valid (default 300)

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID announcing capabilities"
    },
    "capabilities": {
      "type": "array",
      "description": "Array of capability summaries to announce",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "description": "Capability type"
          },
          "materials": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "priceRange": {
            "type": "object",
            "properties": {
              "min": {
                "type": "number"
              },
              "max": {
                "type": "number"
              },
              "currency": {
                "type": "string"
              }
            }
          },
          "queueDepth": {
            "type": "number"
          }
        },
        "required": [
          "type"
        ]
      }
    },
    "ttlSeconds": {
      "type": "number",
      "description": "How long the announcement is valid (default 300)"
    }
  },
  "required": [
    "kernelId",
    "capabilities"
  ]
}

pcc_dht_peers

List known DHT peers and their connection status. Shows which nodes are currently connected to the gossip network.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

pcc_create_scope

Create an execution scope for a job. Scopes define exactly which tool calls are allowed on a kernel during a job, with command budgets, retry limits, and time-to-live. Required before issuing SCOPED WRITE operations (protocol upload, run create, run action).

Parameters9

kernelId	string	required	Kernel ID to create the scope for
jobId	string	optional	Job ID this scope is bound to (optional)
allowedTools	array	required	List of tool names allowed in this scope (e.g. ['ot2_protocol_upload', 'ot2_run_create', 'ot2_run_action'])
allowedPipettes	array	optional	Which pipettes may be used (e.g. ['left'])
allowedSlots	array	optional	Which deck slots may be accessed (e.g. [1, 2, 3, 9])
maxCommands	number	optional	Maximum tool calls allowed in this scope (default 100)
maxRetries	number	optional	Maximum retries allowed (default 3)
ttlMinutes	number	optional	Scope duration in minutes (default 30)
protocolHash	string	optional	SHA-256 hash of the approved protocol content. If set, protocol uploads are hash-verified.

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to create the scope for"
    },
    "jobId": {
      "type": "string",
      "description": "Job ID this scope is bound to (optional)"
    },
    "allowedTools": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "List of tool names allowed in this scope (e.g. ['ot2_protocol_upload', 'ot2_run_create', 'ot2_run_action'])"
    },
    "allowedPipettes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Which pipettes may be used (e.g. ['left'])"
    },
    "allowedSlots": {
      "type": "array",
      "items": {
        "type": "number"
      },
      "description": "Which deck slots may be accessed (e.g. [1, 2, 3, 9])"
    },
    "maxCommands": {
      "type": "number",
      "description": "Maximum tool calls allowed in this scope (default 100)"
    },
    "maxRetries": {
      "type": "number",
      "description": "Maximum retries allowed (default 3)"
    },
    "ttlMinutes": {
      "type": "number",
      "description": "Scope duration in minutes (default 30)"
    },
    "protocolHash": {
      "type": "string",
      "description": "SHA-256 hash of the approved protocol content. If set, protocol uploads are hash-verified."
    }
  },
  "required": [
    "kernelId",
    "allowedTools"
  ]
}

pcc_revoke_scope

Revoke an execution scope immediately (emergency stop). All pending tool calls under this scope are rejected. The kernel enters a stopped state. A new scope must be created to resume.

Parameters1

scopeId

string

required

Scope ID to revoke

Raw schema

{
  "type": "object",
  "properties": {
    "scopeId": {
      "type": "string",
      "description": "Scope ID to revoke"
    }
  },
  "required": [
    "scopeId"
  ]
}

pcc_scope_audit

Get the audit trail for an execution scope — every tool call made under this scope, with validation results, timestamps, and outcomes.

Parameters1

scopeId

string

required

Scope ID to audit

Raw schema

{
  "type": "object",
  "properties": {
    "scopeId": {
      "type": "string",
      "description": "Scope ID to audit"
    }
  },
  "required": [
    "scopeId"
  ]
}

pcc_relay_tool_call

Relay a tool call to a device executor. The brain (LLM) posts tool calls here; the executor (on the device) polls for them and executes locally. Used for the brain/executor split architecture.

Parameters4

kernelId	string	required	Kernel ID of the target device
toolName	string	required	Tool to execute (e.g. 'ot2_health', 'ot2_run_create')
toolArgs	object	required	Arguments for the tool call
scopeId	string	optional	Execution scope ID (required for SCOPED WRITE tools)

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID of the target device"
    },
    "toolName": {
      "type": "string",
      "description": "Tool to execute (e.g. 'ot2_health', 'ot2_run_create')"
    },
    "toolArgs": {
      "type": "object",
      "description": "Arguments for the tool call"
    },
    "scopeId": {
      "type": "string",
      "description": "Execution scope ID (required for SCOPED WRITE tools)"
    }
  },
  "required": [
    "kernelId",
    "toolName",
    "toolArgs"
  ]
}

pcc_get_tool_result

Get the result of a previously relayed tool call. Poll this endpoint until the executor has processed the call and posted results.

Parameters1

callId

string

required

Tool call ID returned from pcc_relay_tool_call

Raw schema

{
  "type": "object",
  "properties": {
    "callId": {
      "type": "string",
      "description": "Tool call ID returned from pcc_relay_tool_call"
    }
  },
  "required": [
    "callId"
  ]
}

pcc_camera_latest

Get the latest camera frame from a kernel as a JSON snapshot (base64 JPEG + metadata). For raw JPEG image, use GET /api/ot2/camera/latest directly.

Parameters1

kernelId

string

required

Kernel ID to get camera frame from

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to get camera frame from"
    }
  },
  "required": [
    "kernelId"
  ]
}

pcc_chat_send

Send a chat message to a kernel's operator or agent. Used for human-in-the-loop communication during job execution, troubleshooting, and escalation.

Parameters3

kernelId	string	required	Kernel ID to send the message to
message	string	required	Message content
role	string	optional	Sender role (default: user)

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to send the message to"
    },
    "message": {
      "type": "string",
      "description": "Message content"
    },
    "role": {
      "type": "string",
      "enum": [
        "user",
        "agent",
        "operator",
        "system"
      ],
      "description": "Sender role (default: user)"
    }
  },
  "required": [
    "kernelId",
    "message"
  ]
}

pcc_chat_history

Get chat history with a kernel. Returns messages between agents, operators, and users for a specific kernel.

Parameters2

kernelId	string	required	Kernel ID to get chat history for
limit	number	optional	Maximum messages to return (default 50)

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to get chat history for"
    },
    "limit": {
      "type": "number",
      "description": "Maximum messages to return (default 50)"
    }
  },
  "required": [
    "kernelId"
  ]
}

approve_registration

Approve a submitted machine registration. Moves it from 'submitted' to 'approved' status, enabling the operator to activate and start accepting jobs.

Parameters1

registrationId

string

required

Registration ID (e.g. 'reg-1234567890')

Raw schema

{
  "type": "object",
  "properties": {
    "registrationId": {
      "type": "string",
      "description": "Registration ID (e.g. 'reg-1234567890')"
    }
  },
  "required": [
    "registrationId"
  ]
}

reject_registration

Reject a machine registration with a reason. The operator can see the rejection reason and resubmit.

Parameters2

registrationId	string	required	Registration ID
reason	string	optional	Reason for rejection

Raw schema

{
  "type": "object",
  "properties": {
    "registrationId": {
      "type": "string",
      "description": "Registration ID"
    },
    "reason": {
      "type": "string",
      "description": "Reason for rejection"
    }
  },
  "required": [
    "registrationId"
  ]
}

activate_registration

Activate an approved registration, making the operator's equipment live on the network and ready to accept jobs.

Parameters1

registrationId

string

required

Registration ID

Raw schema

{
  "type": "object",
  "properties": {
    "registrationId": {
      "type": "string",
      "description": "Registration ID"
    }
  },
  "required": [
    "registrationId"
  ]
}

prove_registration

Fast-track: submit evidence that your device works and get auto-approved + activated immediately. No manual review needed. Submit a photo of test output, device health snapshot, or a full evidence bundle with completion events. If evidence meets requirements, registration jumps straight to 'active'.

Parameters2

registrationId	string	required	Registration ID to prove
evidence	object	required	Evidence proving the device works. Include at least one of: bundleHash+events, photoBase64, or deviceHealth.

Raw schema

{
  "type": "object",
  "properties": {
    "registrationId": {
      "type": "string",
      "description": "Registration ID to prove"
    },
    "evidence": {
      "type": "object",
      "description": "Evidence proving the device works. Include at least one of: bundleHash+events, photoBase64, or deviceHealth.",
      "properties": {
        "bundleHash": {
          "type": "string",
          "description": "SHA-256 hash of the evidence bundle"
        },
        "events": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "description": "Event type: execution_completed, camera_snapshot, power_profile_summary, etc."
              },
              "timestamp": {
                "type": "string",
                "description": "ISO timestamp"
              },
              "payload": {
                "type": "object",
                "description": "Event data"
              }
            }
          },
          "description": "Evidence events from a test job"
        },
        "photoBase64": {
          "type": "string",
          "description": "Base64-encoded photo of test output (printed page, machined part, etc.)"
        },
        "deviceHealth": {
          "type": "object",
          "properties": {
            "status": {
              "type": "string",
              "description": "Device status (e.g. 'idle', 'ready')"
            },
            "model": {
              "type": "string",
              "description": "Device model name"
            },
            "firmware": {
              "type": "string",
              "description": "Firmware version"
            }
          },
          "description": "Live device health snapshot"
        },
        "ipfsCid": {
          "type": "string",
          "description": "IPFS CID if evidence was already uploaded"
        }
      }
    }
  },
  "required": [
    "registrationId",
    "evidence"
  ]
}

list_registrations

List all machine registrations on the network. See pending, approved, active, and rejected registrations. Public endpoint — no auth required.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

get_registration

Get details of a specific machine registration by ID, including capabilities, pricing, operator info, and current status.

Parameters1

registrationId

string

required

Registration ID

Raw schema

{
  "type": "object",
  "properties": {
    "registrationId": {
      "type": "string",
      "description": "Registration ID"
    }
  },
  "required": [
    "registrationId"
  ]
}

near_status

Get NEAR Protocol chain-abstraction integration status. Returns supported chains (near, eth, base, arbitrum, optimism, polygon), supported assets (USDC, USDT, NEAR, ETH, WBTC), and capability flags. Use this to confirm cross-chain settlement is available before requesting quotes.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

near_quote

Get a cross-chain payment quote from the NEAR 1Click solver network (chaindefuser.com). Provides optimal routing and fee estimates for funding PCC escrow contracts using any source asset on any supported chain. Call near_status first to confirm available chains/assets.

Parameters6

fromChain	string	required	Source chain (e.g. 'eth', 'base', 'near', 'arbitrum')
fromAsset	string	required	Source asset symbol (e.g. 'USDC', 'ETH', 'NEAR')
toChain	string	required	Destination chain (e.g. 'base', 'eth')
toAsset	string	required	Destination asset symbol (e.g. 'USDC')
amount	string	required	Amount as an integer string in the smallest denomination (e.g. '1000000' for 1 USDC with 6 decimals)
recipient	string	optional	Recipient address on the destination chain (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "fromChain": {
      "type": "string",
      "description": "Source chain (e.g. 'eth', 'base', 'near', 'arbitrum')"
    },
    "fromAsset": {
      "type": "string",
      "description": "Source asset symbol (e.g. 'USDC', 'ETH', 'NEAR')"
    },
    "toChain": {
      "type": "string",
      "description": "Destination chain (e.g. 'base', 'eth')"
    },
    "toAsset": {
      "type": "string",
      "description": "Destination asset symbol (e.g. 'USDC')"
    },
    "amount": {
      "type": "string",
      "description": "Amount as an integer string in the smallest denomination (e.g. '1000000' for 1 USDC with 6 decimals)"
    },
    "recipient": {
      "type": "string",
      "description": "Recipient address on the destination chain (optional)"
    }
  },
  "required": [
    "fromChain",
    "fromAsset",
    "toChain",
    "toAsset",
    "amount"
  ]
}

near_intent

Submit a cross-chain payment intent to the NEAR 1Click solver network. Creates a signed intent that routes the payment atomically across chains. Call near_quote first to obtain a quoteId. Intents typically settle within 30-60 seconds — poll near_intent_status to track progress.

Parameters3

quoteId	string	required	Quote ID returned from near_quote
workflowId	string	required	PCC workflow or job ID this payment is for
recipient	string	optional	Recipient address on the destination chain (optional)

Raw schema

{
  "type": "object",
  "properties": {
    "quoteId": {
      "type": "string",
      "description": "Quote ID returned from near_quote"
    },
    "workflowId": {
      "type": "string",
      "description": "PCC workflow or job ID this payment is for"
    },
    "recipient": {
      "type": "string",
      "description": "Recipient address on the destination chain (optional)"
    }
  },
  "required": [
    "quoteId",
    "workflowId"
  ]
}

near_intent_status

Check the settlement status of a submitted NEAR 1Click cross-chain payment intent. Statuses progress: pending → submitted → settled | failed. Returns txHash and explorerUrl when settled.

Parameters1

intentId

string

required

Intent ID returned from near_intent

Raw schema

{
  "type": "object",
  "properties": {
    "intentId": {
      "type": "string",
      "description": "Intent ID returned from near_intent"
    }
  },
  "required": [
    "intentId"
  ]
}

protocol_state

Read the PCCProtocol root contract state: current fee rate, total protocol fees collected, total escrow count, and registry addresses. Requires PCC_PROTOCOL_ADDRESS to be configured on the gateway.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

protocol_fee

Calculate the protocol fee for a given USDC amount (6-decimal units). Returns the fee, the net amount after fee, and formatted versions of both. Use this before building escrow contracts to understand the true cost.

Parameters1

amount

string

required

Amount as a BigInt string in USDC 6-decimal units (e.g. '1000000000' = 1000 USDC)

Raw schema

{
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "description": "Amount as a BigInt string in USDC 6-decimal units (e.g. '1000000000' = 1000 USDC)"
    }
  },
  "required": [
    "amount"
  ]
}

protocol_token_fees

Get total protocol fees collected for a specific ERC-20 token address across all escrows. Returns raw wei amount and human-readable formatted value.

Parameters1

tokenAddress

string

required

ERC-20 token contract address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "tokenAddress": {
      "type": "string",
      "description": "ERC-20 token contract address (0x...)"
    }
  },
  "required": [
    "tokenAddress"
  ]
}

protocol_escrow_fees

Get protocol fees collected from a specific escrow contract. Also returns whether the escrow was deployed via the protocol factory. Useful for auditing fee flows.

Parameters1

escrowAddress

string

required

Escrow contract address (0x...)

Raw schema

{
  "type": "object",
  "properties": {
    "escrowAddress": {
      "type": "string",
      "description": "Escrow contract address (0x...)"
    }
  },
  "required": [
    "escrowAddress"
  ]
}

protocol_create_escrow

Create a new MilestoneEscrow contract via the PCCProtocol factory on-chain. Protocol-deployed escrows have fee collection and registry tracking built in. Requires PCC_GATEWAY_PRIVATE_KEY write access.

Parameters4

payer	string	required	Payer EVM address (0x...)
arbiter	string	required	Arbiter EVM address (0x...) — resolves disputes
token	string	required	ERC-20 token address for payment (0x...)
cwmId	string	required	Capability Work Module ID as a 32-byte hex string (0x + 64 chars)

Raw schema

{
  "type": "object",
  "properties": {
    "payer": {
      "type": "string",
      "description": "Payer EVM address (0x...)"
    },
    "arbiter": {
      "type": "string",
      "description": "Arbiter EVM address (0x...) — resolves disputes"
    },
    "token": {
      "type": "string",
      "description": "ERC-20 token address for payment (0x...)"
    },
    "cwmId": {
      "type": "string",
      "description": "Capability Work Module ID as a 32-byte hex string (0x + 64 chars)"
    }
  },
  "required": [
    "payer",
    "arbiter",
    "token",
    "cwmId"
  ]
}

pcc_dht_metrics

Get a snapshot of DHT telemetry counters and recent events. Returns message counts, peer connection stats, query/announce rates, and a list of the last 50 metric events. Use for monitoring network health.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

marketplace_categories

List all supplies and materials marketplace categories with the count of active listings in each. Categories cover the full spectrum of physical production inputs: raw metals, plastics, lab reagents, consumables, electronics, tooling, and more.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

marketplace_list_listings

Search and filter supplies/materials marketplace listings. Operators buy raw materials here to fulfill capability contracts. Filter by category, in-stock status, location, or free-text query.

Parameters4

category	string	optional	Filter by category: raw-metals, plastics-polymers, lab-reagents, lab-consumables, electronics, chemicals, biologicals, tooling, packaging, calibration, safety, other
query	string	optional	Full-text search across name, description, and tags
inStock	string	optional	Filter to only in-stock listings
location	string	optional	Filter by region (e.g. 'US-Midwest', 'EU-West', 'Asia-Pacific')

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "description": "Filter by category: raw-metals, plastics-polymers, lab-reagents, lab-consumables, electronics, chemicals, biologicals, tooling, packaging, calibration, safety, other"
    },
    "query": {
      "type": "string",
      "description": "Full-text search across name, description, and tags"
    },
    "inStock": {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "description": "Filter to only in-stock listings"
    },
    "location": {
      "type": "string",
      "description": "Filter by region (e.g. 'US-Midwest', 'EU-West', 'Asia-Pacific')"
    }
  },
  "required": []
}

marketplace_get_listing

Get full details of a specific supplies/materials marketplace listing by ID. Returns pricing, availability, lead time, location, and tags.

Parameters1

string

required

Listing ID (e.g. 'lst-al6061-bar')

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Listing ID (e.g. 'lst-al6061-bar')"
    }
  },
  "required": [
    "id"
  ]
}

marketplace_create_listing

Create a new supplies/materials listing in the marketplace. Suppliers post available raw materials, lab reagents, tooling, or consumables for other operators to purchase.

Parameters12

sellerId	string	optional	Supplier entity ID
category	string	required	Category: raw-metals, plastics-polymers, lab-reagents, lab-consumables, electronics, chemicals, biologicals, tooling, packaging, calibration, safety, other
name	string	required	Product name
description	string	optional	Detailed product description
unit	string	required	Unit of sale: kg, L, each, box, plate, etc.
pricePerUnit	number	required	Price per unit in USDC
minOrder	number	optional	Minimum order quantity
maxOrder	number	optional	Maximum order quantity
inStock	boolean	optional	Whether the item is currently available
leadTimeDays	number	optional	Estimated lead time in business days
location	string	optional	Supplier region or country
tags	array	optional	Search tags

Raw schema

{
  "type": "object",
  "properties": {
    "sellerId": {
      "type": "string",
      "description": "Supplier entity ID"
    },
    "category": {
      "type": "string",
      "description": "Category: raw-metals, plastics-polymers, lab-reagents, lab-consumables, electronics, chemicals, biologicals, tooling, packaging, calibration, safety, other"
    },
    "name": {
      "type": "string",
      "description": "Product name"
    },
    "description": {
      "type": "string",
      "description": "Detailed product description"
    },
    "unit": {
      "type": "string",
      "description": "Unit of sale: kg, L, each, box, plate, etc."
    },
    "pricePerUnit": {
      "type": "number",
      "description": "Price per unit in USDC"
    },
    "minOrder": {
      "type": "number",
      "description": "Minimum order quantity"
    },
    "maxOrder": {
      "type": "number",
      "description": "Maximum order quantity"
    },
    "inStock": {
      "type": "boolean",
      "description": "Whether the item is currently available"
    },
    "leadTimeDays": {
      "type": "number",
      "description": "Estimated lead time in business days"
    },
    "location": {
      "type": "string",
      "description": "Supplier region or country"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Search tags"
    }
  },
  "required": [
    "category",
    "name",
    "pricePerUnit",
    "unit"
  ]
}

marketplace_update_listing

Update an existing supplies/materials listing (price, stock status, description, etc.). Pass only the fields you want to change.

Parameters6

id	string	required	Listing ID to update
pricePerUnit	number	optional	New price per unit in USDC
inStock	boolean	optional	Stock availability
description	string	optional	Updated description
leadTimeDays	number	optional	Updated lead time in days
tags	array	optional	Updated search tags

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Listing ID to update"
    },
    "pricePerUnit": {
      "type": "number",
      "description": "New price per unit in USDC"
    },
    "inStock": {
      "type": "boolean",
      "description": "Stock availability"
    },
    "description": {
      "type": "string",
      "description": "Updated description"
    },
    "leadTimeDays": {
      "type": "number",
      "description": "Updated lead time in days"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Updated search tags"
    }
  },
  "required": [
    "id"
  ]
}

marketplace_delete_listing

Remove a supplies/materials listing from the marketplace. The listing is immediately hidden from search results.

Parameters1

string

required

Listing ID to remove

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Listing ID to remove"
    }
  },
  "required": [
    "id"
  ]
}

marketplace_place_order

Place a purchase order for supplies or materials. Calculates total price automatically (quantity × pricePerUnit). Returns an order with 'pending' status. Optionally links to an on-chain escrow for trustless settlement.

Parameters4

listingId	string	required	Listing ID to order from
quantity	number	required	Quantity to order (must meet listing minOrder/maxOrder)
buyerId	string	optional	Buyer entity ID (operator kernel ID, etc.)
escrowAddress	string	optional	Optional on-chain escrow address for trustless settlement

Raw schema

{
  "type": "object",
  "properties": {
    "listingId": {
      "type": "string",
      "description": "Listing ID to order from"
    },
    "quantity": {
      "type": "number",
      "description": "Quantity to order (must meet listing minOrder/maxOrder)"
    },
    "buyerId": {
      "type": "string",
      "description": "Buyer entity ID (operator kernel ID, etc.)"
    },
    "escrowAddress": {
      "type": "string",
      "description": "Optional on-chain escrow address for trustless settlement"
    }
  },
  "required": [
    "listingId",
    "quantity"
  ]
}

marketplace_list_orders

List marketplace supply orders. Filter by buyerId, sellerId, or status. Returns order history with pricing and status.

Parameters3

buyerId	string	optional	Filter to orders placed by this buyer
sellerId	string	optional	Filter to orders received by this seller
status	string	optional	Filter by order status

Raw schema

{
  "type": "object",
  "properties": {
    "buyerId": {
      "type": "string",
      "description": "Filter to orders placed by this buyer"
    },
    "sellerId": {
      "type": "string",
      "description": "Filter to orders received by this seller"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "confirmed",
        "shipped",
        "delivered",
        "cancelled"
      ],
      "description": "Filter by order status"
    }
  },
  "required": []
}

marketplace_get_order

Get details of a specific supply order including the associated listing details, quantity, total price, status, and optional escrow address.

Parameters1

string

required

Order ID (e.g. 'ord-demo-001')

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Order ID (e.g. 'ord-demo-001')"
    }
  },
  "required": [
    "id"
  ]
}

system_telemetry

Raw system state dump — actual DB rows for kernels, devices, jobs, evidence, registrations, capabilities, agent conversations, audit log. No fake numbers, no summaries.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

operator_poll_jobs

Operator polls for pending jobs assigned to their kernel. Returns queued jobs ready for execution. Used by pcc-node daemon.

Parameters1

kernelId

string

required

Kernel ID to poll jobs for

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to poll jobs for"
    }
  },
  "required": [
    "kernelId"
  ]
}

operator_push_evidence

Operator pushes evidence bundle from a completed job execution. Contains device ID, execution timestamp, result payload, and event timeline.

Parameters3

jobId	string	required
kernelId	string	required
evidence	object	required

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string"
    },
    "kernelId": {
      "type": "string"
    },
    "evidence": {
      "type": "object"
    }
  },
  "required": [
    "jobId",
    "kernelId",
    "evidence"
  ]
}

operator_heartbeat

Operator sends heartbeat with capability re-announcement. Keeps the kernel alive on the network and updates available capabilities.

Parameters2

kernelId	string	required
capabilities	array	optional

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string"
    },
    "capabilities": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  },
  "required": [
    "kernelId"
  ]
}

operator_update_job_status

Operator updates job status during execution (in_progress, completed, failed). Called by pcc-node as jobs progress.

Parameters4

jobId	string	required
kernelId	string	required
status	string	required
metadata	object	optional

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string"
    },
    "kernelId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "in_progress",
        "completed",
        "failed"
      ]
    },
    "metadata": {
      "type": "object"
    }
  },
  "required": [
    "jobId",
    "kernelId",
    "status"
  ]
}

pcc_submit_paid_job

Fast-track paid job: one call from DHT discovery to funded escrow + active scope. Auto-negotiates, quotes, creates escrow with milestones, creates execution scope. Returns jobId, scopeId, escrowId, quote with pricing adjustments, contract terms. For testnet, escrow is mock-funded automatically.

Parameters5

kernelId	string	required	Target kernel ID (from DHT query)
capabilityType	string	required	e.g. 'liquid-handler', 'fdm', 'cnc-3axis'
parameters	object	optional	Job parameters (protocolType, volume, materials, etc.)
paymentMethod	string	optional	Payment method (testnet-mock for demo)
userAgentId	string	required	Your agent/user ID

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Target kernel ID (from DHT query)"
    },
    "capabilityType": {
      "type": "string",
      "description": "e.g. 'liquid-handler', 'fdm', 'cnc-3axis'"
    },
    "parameters": {
      "type": "object",
      "description": "Job parameters (protocolType, volume, materials, etc.)"
    },
    "paymentMethod": {
      "type": "string",
      "enum": [
        "escrow",
        "testnet-mock"
      ],
      "description": "Payment method (testnet-mock for demo)"
    },
    "userAgentId": {
      "type": "string",
      "description": "Your agent/user ID"
    }
  },
  "required": [
    "kernelId",
    "capabilityType",
    "userAgentId"
  ]
}

pcc_job_complete

Complete a job: gathers tool call audit trail from execution scopes, builds evidence bundle with SHA-256 hash, stores evidence, revokes scopes, and settles escrow (mock or real).

Parameters2

jobId	string	required	Job ID to complete
message	string	optional	Completion message or notes

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Job ID to complete"
    },
    "message": {
      "type": "string",
      "description": "Completion message or notes"
    }
  },
  "required": [
    "jobId"
  ]
}

pcc_job_settlement

Get settlement status for a completed job: escrow address, evidence hash, milestones with amounts and status, paid amount, currency, and linked negotiation session.

Parameters1

jobId

string

required

Job ID

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Job ID"
    }
  },
  "required": [
    "jobId"
  ]
}

pcc_get_tool_manifest

Get the tool manifest for a kernel's device type. Lists all available tools with their safety classification (read, safe_control, scoped_write, privileged) and input schemas. Use to understand what tools are available before making tool calls.

Parameters1

kernelId

string

required

Kernel ID

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID"
    }
  },
  "required": [
    "kernelId"
  ]
}

pcc_relay_generic_tool_call

Relay a tool call to any kernel's device executor via the generic relay (not OT-2 specific). Works with any device type. Safe tools (read/safe_control) don't need a scope. Scoped write tools require an active execution scope. Returns a call ID — poll pcc_get_tool_result for the response.

Parameters4

kernelId	string	required	Target kernel ID
toolName	string	required	Tool name from the device manifest
args	object	optional	Tool arguments
scopeId	string	optional	Execution scope ID (required for write operations)

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Target kernel ID"
    },
    "toolName": {
      "type": "string",
      "description": "Tool name from the device manifest"
    },
    "args": {
      "type": "object",
      "description": "Tool arguments"
    },
    "scopeId": {
      "type": "string",
      "description": "Execution scope ID (required for write operations)"
    }
  },
  "required": [
    "kernelId",
    "toolName"
  ]
}

pcc_submit_request

Submit a high-level capability request in natural language. The system automatically decomposes it into a capability DAG with dependencies, timelines, and budget allocation across fabrication, design, assembly, electronics, software, logistics, and verification nodes. Returns the request with full decomposed DAG. Example: 'Build a cute animatronic plush desk robot with servo-driven animations'.

Parameters8

title	string	required	Short title for the request
description	string	required	Full natural language description of what needs to be built or done
budget	number	optional	Total budget in USDC (default: 1000)
deadline	string	optional	ISO 8601 deadline (default: 7 days from now)
urgency	string	optional	Urgency level — affects cost multipliers (emergency: 2x cost, 0.5x time)
currency	string	optional	Currency (default: USDC)
requesterEmail	string	optional	Requester email for notifications
requesterWallet	string	optional	Requester wallet address for payments

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Short title for the request"
    },
    "description": {
      "type": "string",
      "description": "Full natural language description of what needs to be built or done"
    },
    "budget": {
      "type": "number",
      "description": "Total budget in USDC (default: 1000)"
    },
    "deadline": {
      "type": "string",
      "description": "ISO 8601 deadline (default: 7 days from now)"
    },
    "urgency": {
      "type": "string",
      "enum": [
        "standard",
        "rush",
        "emergency"
      ],
      "description": "Urgency level — affects cost multipliers (emergency: 2x cost, 0.5x time)"
    },
    "currency": {
      "type": "string",
      "description": "Currency (default: USDC)"
    },
    "requesterEmail": {
      "type": "string",
      "description": "Requester email for notifications"
    },
    "requesterWallet": {
      "type": "string",
      "description": "Requester wallet address for payments"
    }
  },
  "required": [
    "title",
    "description"
  ]
}

pcc_list_requests

List all capability requests with optional filtering. Shows status, decomposed DAG summary, estimated costs, and timelines.

Parameters3

status	string	optional	Filter by status
urgency	string	optional	Filter by urgency
requesterEmail	string	optional	Filter by requester email

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "draft",
        "decomposing",
        "published",
        "in_progress",
        "completed",
        "cancelled"
      ],
      "description": "Filter by status"
    },
    "urgency": {
      "type": "string",
      "enum": [
        "standard",
        "rush",
        "emergency"
      ],
      "description": "Filter by urgency"
    },
    "requesterEmail": {
      "type": "string",
      "description": "Filter by requester email"
    }
  },
  "required": []
}

pcc_get_request

Get a capability request by ID with the full decomposed DAG — all capability nodes, their dependencies, estimated costs/hours, assigned operators, and linked bounty IDs.

Parameters1

requestId

string

required

Request ID

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Request ID"
    }
  },
  "required": [
    "requestId"
  ]
}

pcc_decompose_request

Re-trigger decomposition of an existing capability request. Overwrites the existing capability DAG with a fresh decomposition. Useful after updating the description or budget.

Parameters1

requestId

string

required

Request ID to decompose

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Request ID to decompose"
    }
  },
  "required": [
    "requestId"
  ]
}

pcc_publish_request

Publish all pending capability nodes in a request as bounties. Each node becomes a bidding opportunity for operators. Returns the list of created bounty IDs linked to each capability node.

Parameters1

requestId

string

required

Request ID to publish

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Request ID to publish"
    }
  },
  "required": [
    "requestId"
  ]
}

pcc_get_request_dag

Get the capability DAG (directed acyclic graph) for a request as adjacency data — nodes with all fields plus explicit edges showing dependency relationships. Useful for visualization or workflow planning.

Parameters1

requestId

string

required

Request ID

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Request ID"
    }
  },
  "required": [
    "requestId"
  ]
}

pcc_get_request_critical_path

Get the critical path (longest dependency chain) for a capability request. The critical path determines the minimum calendar time to complete the request. Returns node IDs in order, the full node details, and total hours on the critical path.

Parameters1

requestId

string

required

Request ID

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Request ID"
    }
  },
  "required": [
    "requestId"
  ]
}

pcc_assign_node_operator

Assign an operator to a specific capability node within a request. The node status changes to 'assigned'. Operators claim nodes to indicate they will execute that capability.

Parameters3

requestId	string	required	Request ID
nodeId	string	required	Capability node ID
operatorId	string	required	Operator kernel ID or wallet address

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Request ID"
    },
    "nodeId": {
      "type": "string",
      "description": "Capability node ID"
    },
    "operatorId": {
      "type": "string",
      "description": "Operator kernel ID or wallet address"
    }
  },
  "required": [
    "requestId",
    "nodeId",
    "operatorId"
  ]
}

pcc_update_node_status

Update the status of a capability node within a request. Valid transitions: pending → bidding → assigned → in_progress → completed (or failed). When all nodes complete, the request automatically moves to completed.

Parameters3

requestId	string	required	Request ID
nodeId	string	required	Capability node ID
status	string	required	New status for the node

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Request ID"
    },
    "nodeId": {
      "type": "string",
      "description": "Capability node ID"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "bidding",
        "assigned",
        "in_progress",
        "completed",
        "failed"
      ],
      "description": "New status for the node"
    }
  },
  "required": [
    "requestId",
    "nodeId",
    "status"
  ]
}

pcc_update_request

Update a capability request's title, description, budget, deadline, urgency, or contact info. Does not re-decompose — call pcc_decompose_request afterwards if you want a fresh DAG.

Parameters8

requestId	string	required	Request ID
title	string	optional
description	string	optional
budget	number	optional
deadline	string	optional
urgency	string	optional
requesterEmail	string	optional
requesterWallet	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Request ID"
    },
    "title": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "budget": {
      "type": "number"
    },
    "deadline": {
      "type": "string"
    },
    "urgency": {
      "type": "string",
      "enum": [
        "standard",
        "rush",
        "emergency"
      ]
    },
    "requesterEmail": {
      "type": "string"
    },
    "requesterWallet": {
      "type": "string"
    }
  },
  "required": [
    "requestId"
  ]
}

pcc_cancel_request

Cancel a capability request. Cancelled requests cannot be updated, decomposed, or published. This is a soft delete — the request remains visible with status 'cancelled'.

Parameters1

requestId

string

required

Request ID to cancel

Raw schema

{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Request ID to cancel"
    }
  },
  "required": [
    "requestId"
  ]
}

pcc_generate_ui

Generate a dynamic visual interface and serve it locally via pcc-node's UI server (localhost:3200). Supports built-in templates (plate-layout, protocol-builder, job-status, camera-viewer, device-config) or custom HTML. The UI appears in the operator's browser. Form submissions are queued for the agent to read via pcc_get_ui_submissions.

Parameters4

template	string	required	Built-in template name or 'custom'
filename	string	optional	Output filename (e.g. 'my-form.html')
content	string	optional	Custom HTML content (when template='custom')
title	string	optional	UI title

Raw schema

{
  "type": "object",
  "properties": {
    "template": {
      "type": "string",
      "description": "Built-in template name or 'custom'"
    },
    "filename": {
      "type": "string",
      "description": "Output filename (e.g. 'my-form.html')"
    },
    "content": {
      "type": "string",
      "description": "Custom HTML content (when template='custom')"
    },
    "title": {
      "type": "string",
      "description": "UI title"
    }
  },
  "required": [
    "template"
  ]
}

pcc_oracle_status

Check if the PCC verification oracle is online. Returns the oracle's EIP-712 signing address and chain ID. The oracle is required for all escrow settlements — no attestation means no fund release.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

pcc_oracle_verify

Submit evidence for oracle verification. The oracle checks: evidence exists, hash matches, tier requirements met, no replay, operator identity valid. Returns a signed EIP-712 attestation that the escrow contract requires to release funds. This is the critical path — every settlement flows through this endpoint.

Parameters5

escrowAddress	string	required	Escrow contract address
jobId	string	required	PCC job ID
kernelId	string	required	Operator kernel ID
evidenceHash	string	required	SHA-256 hash of evidence bundle
assuranceTier	integer	optional	Evidence tier (0=none, 1=basic, 2=full, 3=ZK)

Raw schema

{
  "type": "object",
  "properties": {
    "escrowAddress": {
      "type": "string",
      "description": "Escrow contract address"
    },
    "jobId": {
      "type": "string",
      "description": "PCC job ID"
    },
    "kernelId": {
      "type": "string",
      "description": "Operator kernel ID"
    },
    "evidenceHash": {
      "type": "string",
      "description": "SHA-256 hash of evidence bundle"
    },
    "assuranceTier": {
      "type": "integer",
      "enum": [
        0,
        1,
        2,
        3
      ],
      "description": "Evidence tier (0=none, 1=basic, 2=full, 3=ZK)"
    }
  },
  "required": [
    "escrowAddress",
    "jobId",
    "kernelId",
    "evidenceHash"
  ]
}

pcc_protocol_fee

Get the current protocol fee rate (2.35%, immutable) and fee recipient address. The fee is hardcoded in the PCCProtocol smart contract — no admin, no governance, no upgrade can change it.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

create_capability

Register a capability instance for a kernel. Required before submitting jobs — the gateway needs at least one capability per kernel. Creates a liquid-handler, fdm, cnc-3axis, or other capability type.

Parameters4

kernelId	string	required	Kernel ID to register capability for
type	string	required	Capability type (e.g. liquid-handler, fdm, cnc-3axis, laser-cut, document-printing)
name	string	optional	Human-readable name for the capability
description	string	optional	Description of what this capability does

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID to register capability for"
    },
    "type": {
      "type": "string",
      "description": "Capability type (e.g. liquid-handler, fdm, cnc-3axis, laser-cut, document-printing)"
    },
    "name": {
      "type": "string",
      "description": "Human-readable name for the capability"
    },
    "description": {
      "type": "string",
      "description": "Description of what this capability does"
    }
  },
  "required": [
    "kernelId",
    "type"
  ]
}

kernel_heartbeat

Send a per-kernel heartbeat to keep the kernel marked online. Used by pcc-node daemons as an alternative to the operator relay heartbeat.

Parameters3

kernelId	string	required	Kernel ID
status	string	optional	Kernel status (online/offline)
capabilities	array	optional	Optional capability announcements

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID"
    },
    "status": {
      "type": "string",
      "description": "Kernel status (online/offline)",
      "default": "online"
    },
    "capabilities": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Optional capability announcements"
    }
  },
  "required": [
    "kernelId"
  ]
}

kernel_announce_capabilities

Announce capabilities for a kernel. Used by pcc-node daemons after hardware detection to register what the kernel can do.

Parameters4

kernelId	string	required	Kernel ID
capabilities	array	required	Capability objects to announce
devices	array	optional	Device IDs that back these capabilities
signature	string	optional	Ed25519 signature of the announcement

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID"
    },
    "capabilities": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Capability objects to announce"
    },
    "devices": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Device IDs that back these capabilities"
    },
    "signature": {
      "type": "string",
      "description": "Ed25519 signature of the announcement"
    }
  },
  "required": [
    "kernelId",
    "capabilities"
  ]
}

send_diagnostics

Upload an encrypted diagnostic bundle when the operator's node has problems. The bundle is encrypted client-side with a retrieval code the operator must share with support before logs can be read. Use this when the operator reports errors, crashes, or misbehavior. The pcc-node CLI runs `pcc-node logs --send` locally to collect+encrypt; prefer that path when available. This tool is for agent-driven uploads when the bundle is already prepared.

Parameters7

kernelId	string	required	Kernel ID the diagnostics came from
encrypted	object	required	Encrypted bundle payload
bundleHash	string	optional	sha256 of plaintext bundle
bundleSize	number	optional	Size of encrypted payload in bytes
logLineCount	number	optional	How many log lines are in the bundle
systemPlatform	string	optional	e.g. Linux-5.15, Darwin-23, Windows-10
collectedAt	string	optional	ISO timestamp when bundle was collected

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Kernel ID the diagnostics came from"
    },
    "encrypted": {
      "type": "object",
      "description": "Encrypted bundle payload",
      "properties": {
        "ciphertext_b64": {
          "type": "string"
        },
        "iv_b64": {
          "type": "string"
        },
        "salt_b64": {
          "type": "string"
        },
        "tag_b64": {
          "type": "string"
        }
      },
      "required": [
        "ciphertext_b64",
        "iv_b64",
        "salt_b64",
        "tag_b64"
      ]
    },
    "bundleHash": {
      "type": "string",
      "description": "sha256 of plaintext bundle"
    },
    "bundleSize": {
      "type": "number",
      "description": "Size of encrypted payload in bytes"
    },
    "logLineCount": {
      "type": "number",
      "description": "How many log lines are in the bundle"
    },
    "systemPlatform": {
      "type": "string",
      "description": "e.g. Linux-5.15, Darwin-23, Windows-10"
    },
    "collectedAt": {
      "type": "string",
      "description": "ISO timestamp when bundle was collected"
    }
  },
  "required": [
    "kernelId",
    "encrypted"
  ]
}

send_support_message

Send an operator support message to the PCC team. Creates a new support thread or appends to the operator's existing open thread. Can optionally attach a diagnostic retrieval code (from send_diagnostics) so support staff can decrypt logs. Discord webhook fires on every new message, so expect fast response. Use this whenever the operator says something is broken, confusing, or not behaving as expected.

Parameters6

kernelId	string	required	Operator's kernel ID
kernelName	string	optional	Human-readable kernel name
message	string	required	The support message text — describe the problem concretely
subject	string	optional	Optional thread subject (auto-generated from message if omitted)
retrievalCode	string	optional	Optional diagnostic retrieval code to attach (from send_diagnostics)
systemInfo	object	optional	Optional system context (platform, nodeVersion, daemonRunning, gatewayReachable)

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Operator's kernel ID"
    },
    "kernelName": {
      "type": "string",
      "description": "Human-readable kernel name"
    },
    "message": {
      "type": "string",
      "description": "The support message text — describe the problem concretely"
    },
    "subject": {
      "type": "string",
      "description": "Optional thread subject (auto-generated from message if omitted)"
    },
    "retrievalCode": {
      "type": "string",
      "description": "Optional diagnostic retrieval code to attach (from send_diagnostics)"
    },
    "systemInfo": {
      "type": "object",
      "description": "Optional system context (platform, nodeVersion, daemonRunning, gatewayReachable)"
    }
  },
  "required": [
    "kernelId",
    "message"
  ]
}

check_support_replies

Check for admin replies on the operator's support threads. Call this periodically or when the operator asks 'did they respond yet?'. Returns all threads for this kernel and a hasUnreadReplies boolean indicating new admin messages.

Parameters1

kernelId

string

required

Operator's kernel ID

Raw schema

{
  "type": "object",
  "properties": {
    "kernelId": {
      "type": "string",
      "description": "Operator's kernel ID"
    }
  },
  "required": [
    "kernelId"
  ]
}

reply_to_support_thread

Reply to an existing support thread. Use when the operator wants to add information to a thread started earlier. Needs the threadId from check_support_replies or the original send_support_message response.

Parameters3

threadId	string	required	Thread ID to reply to
message	string	required	Reply message
retrievalCode	string	optional	Optional diagnostic retrieval code to attach

Raw schema

{
  "type": "object",
  "properties": {
    "threadId": {
      "type": "string",
      "description": "Thread ID to reply to"
    },
    "message": {
      "type": "string",
      "description": "Reply message"
    },
    "retrievalCode": {
      "type": "string",
      "description": "Optional diagnostic retrieval code to attach"
    }
  },
  "required": [
    "threadId",
    "message"
  ]
}

pcc_capture_challenge

Issue a fresh block-anchored CaptureNonceChallenge for a job. The operator's device must render this nonce into the captured media (QR code, audio tone, etc.) before calling pcc_capture_upload. The nonce is derived from (challengeId, latest blockHash, workOutputRoot) so captures cannot be pre-computed. Returns challengeId, 64-char hex nonce, blockNumber, maxAgeSeconds (clamped to 120).

Parameters3

jobId	string	required	PCC job ID the capture belongs to
declaredClass	string	required	Capture class the operator plans to claim. Determines which gates the verifier will run.
requestedTtlSeconds	integer	optional	Requested challenge lifetime in seconds. Clamped to 120 server-side.

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "PCC job ID the capture belongs to"
    },
    "declaredClass": {
      "type": "string",
      "enum": [
        "CC0",
        "CC1",
        "CC2",
        "CC3",
        "CC4",
        "CC5"
      ],
      "description": "Capture class the operator plans to claim. Determines which gates the verifier will run."
    },
    "requestedTtlSeconds": {
      "type": "integer",
      "description": "Requested challenge lifetime in seconds. Clamped to 120 server-side."
    }
  },
  "required": [
    "jobId",
    "declaredClass"
  ]
}

pcc_capture_upload

Upload a capture (photo / video / audio / sensor clip) with its CaptureManifest for G1..G6 verification. Bytes are base64-encoded inline; optional base64 C2PA manifest bytes can be supplied for CC3+ claims. The server runs the 6-gate CaptureVerifier and persists a PASS/PARTIAL/FAIL verdict. Returns {verdictId, verdict, verifiedClass, gatesPassed, gatesFailed, warnings, anchorCandidate, captureHash, manifestHash}.

Parameters8

manifest	object	required	CaptureManifest — ALCOA+-ready metadata: class, declaredAt (ISO-8601), deviceFingerprint, mediaHash (sha256:<hex>), optional challengeId. See CaptureManifestSchema in @pcc/spec.
captureBytesBase64	string	required	Base64-encoded capture bytes (image / video / audio / sensor clip). Hash must match manifest.mediaHash.
c2paManifestBase64	string	optional	Optional base64-encoded C2PA manifest JUMBF bytes. Required when manifest.class >= CC3.
jobId	string	optional	Job ID for telemetry binding. Falls back to manifest.jobId if omitted.
operatorId	string	optional	Explicit operator ID. Falls back to the authenticated session userId.
challengeId	string	optional	Challenge UUID to re-bind to the in-memory challenge cache (G3 freshness gate).
visualNonceEcho	string	optional	The visual nonce value the operator rendered in-scene (QR payload, audio tone id, etc.).
submittedAt	integer	optional	Client-submitted timestamp (epoch ms). Used in drift detection.

Raw schema

{
  "type": "object",
  "properties": {
    "manifest": {
      "type": "object",
      "description": "CaptureManifest — ALCOA+-ready metadata: class, declaredAt (ISO-8601), deviceFingerprint, mediaHash (sha256:<hex>), optional challengeId. See CaptureManifestSchema in @pcc/spec."
    },
    "captureBytesBase64": {
      "type": "string",
      "description": "Base64-encoded capture bytes (image / video / audio / sensor clip). Hash must match manifest.mediaHash."
    },
    "c2paManifestBase64": {
      "type": "string",
      "description": "Optional base64-encoded C2PA manifest JUMBF bytes. Required when manifest.class >= CC3."
    },
    "jobId": {
      "type": "string",
      "description": "Job ID for telemetry binding. Falls back to manifest.jobId if omitted."
    },
    "operatorId": {
      "type": "string",
      "description": "Explicit operator ID. Falls back to the authenticated session userId."
    },
    "challengeId": {
      "type": "string",
      "description": "Challenge UUID to re-bind to the in-memory challenge cache (G3 freshness gate)."
    },
    "visualNonceEcho": {
      "type": "string",
      "description": "The visual nonce value the operator rendered in-scene (QR payload, audio tone id, etc.)."
    },
    "submittedAt": {
      "type": "integer",
      "description": "Client-submitted timestamp (epoch ms). Used in drift detection."
    }
  },
  "required": [
    "manifest",
    "captureBytesBase64"
  ]
}

pcc_capture_anchor

Anchor a PASS + anchor-candidate capture verdict to CaptureClassRegistry on-chain (Base Sepolia by default). Rejects FAIL/PARTIAL verdicts. Idempotent — re-submitting the same verdictId returns the existing anchor row. Returns 202 {status:'deferred'} if CaptureClassRegistry is not yet deployed (CAPTURE_REGISTRY_ADDRESS unset).

Parameters1

verdictId

string

required

The verdictId returned by pcc_capture_upload. Must be a PASS verdict with anchorCandidate=true.

Raw schema

{
  "type": "object",
  "properties": {
    "verdictId": {
      "type": "string",
      "description": "The verdictId returned by pcc_capture_upload. Must be a PASS verdict with anchorCandidate=true."
    }
  },
  "required": [
    "verdictId"
  ]
}

pcc_capture_status

Fetch the combined verdict + on-chain anchor view for a single capture. Mirrors the verifier's DB shape plus the anchor tx metadata (txHash, blockNumber, gasUsed, explorerUrl). Anchor is null if the verdict was never anchored.

Parameters1

verdictId

string

required

Capture verdict UUID (from pcc_capture_upload).

Raw schema

{
  "type": "object",
  "properties": {
    "verdictId": {
      "type": "string",
      "description": "Capture verdict UUID (from pcc_capture_upload)."
    }
  },
  "required": [
    "verdictId"
  ]
}

pcc_list_verdicts

List recent capture verdicts, newest first. Optionally filter by jobId. Default limit is 50, capped at 200 server-side. Returns {verdicts, count, limit, jobId}.

Parameters2

jobId	string	optional	Filter by job ID. Omit for all verdicts across jobs.
limit	integer	optional	Maximum rows returned (default 50, hard cap 200).

Raw schema

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Filter by job ID. Omit for all verdicts across jobs."
    },
    "limit": {
      "type": "integer",
      "description": "Maximum rows returned (default 50, hard cap 200)."
    }
  },
  "required": []
}

pcc_capture_class_registry

Look up a capture's on-chain anchor record in CaptureClassRegistry by its 32-byte captureHash. Returns the registry address, captureHash, and decoded anchor tuple (declaredClass, verifiedClass, manifestHash, submittedBy, jobId, challengeId, blockAnchor, capturedAt, attestationsRoot, attesterCount). onchain is null if the capture was never anchored. Returns 202 deferred when CaptureClassRegistry is not yet deployed.

Parameters1

captureHash

string

required

Capture hash (32-byte). Accepts 0x-prefixed or unprefixed hex, or sha256:<hex> format. Padded server-side to bytes32.

Raw schema

{
  "type": "object",
  "properties": {
    "captureHash": {
      "type": "string",
      "description": "Capture hash (32-byte). Accepts 0x-prefixed or unprefixed hex, or sha256:<hex> format. Padded server-side to bytes32."
    }
  },
  "required": [
    "captureHash"
  ]
}

pcc_verifier_health

Report CaptureVerifier health: which adapters are loaded (c2pa, webauthn, appattest, playintegrity), their staleness status, in-memory challenge cache size, whether CaptureClassRegistry is deployed, and the active PCC_NETWORK. Use this to diagnose why a capture class is being rejected or degraded.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

pcc_orchestrator_list_templates

List the orchestrator templates the dashboard's chat console can drive. Each entry includes slug, display_name, description, produces_kind, capability_class (physical | digital), greeting, and api_base (the route prefix that serves the six session-driver routes for that template). Public — no auth required.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

pcc_orchestrator_match_capabilities

Heuristic template matcher. Pass a free-text description of what you want to onboard (e.g. 'I run a CNC milling shop' or 'I have a Postgres database with a GraphQL endpoint') and the matcher returns all templates ranked by keyword score with a 'reason' string per match. Public — no auth required.

Parameters1

input

string

required

Free-text description of what you want to onboard.

Raw schema

{
  "type": "object",
  "properties": {
    "input": {
      "type": "string",
      "description": "Free-text description of what you want to onboard."
    }
  },
  "required": [
    "input"
  ]
}

pcc_onboard_session_start

Start a new physical-operator onboarding session. Returns a session_id used by every subsequent /api/onboard/* call. Auth-required.

Parameters2

name	string	required	Operator / company name (e.g. 'Oakland Titanium Mills').
url	string	optional	Optional company website. If supplied, the orchestrator scrapes it on the next /scrape call.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Operator / company name (e.g. 'Oakland Titanium Mills')."
    },
    "url": {
      "type": "string",
      "description": "Optional company website. If supplied, the orchestrator scrapes it on the next /scrape call."
    }
  },
  "required": [
    "name"
  ]
}

pcc_onboard_session_scrape

Scrape a URL into the running physical-operator onboarding session. Triggers a stealth fetch + structured extraction (machines, hours, services, certifications). Returns a small JSON summary; full extraction is appended to the session's running profile and visible via /live-data. Auth-required.

Parameters2

id	string	required	Session id returned by pcc_onboard_session_start.
url	string	required	URL to scrape (e.g. company About page).

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Session id returned by pcc_onboard_session_start."
    },
    "url": {
      "type": "string",
      "description": "URL to scrape (e.g. company About page)."
    }
  },
  "required": [
    "id",
    "url"
  ]
}

pcc_onboard_session_ingest_docs

Queue documents (datasheets, SOPs, MOPs, certifications) for ingestion into a physical-operator onboarding session. Document URLs may be local:// for files dropped in the chat console or full https:// URLs. Auth-required.

Parameters2

id	string	required	Session id returned by pcc_onboard_session_start.
doc_urls	array	required	URLs of documents to ingest. Mix of local:// and https:// is fine.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Session id returned by pcc_onboard_session_start."
    },
    "doc_urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "URLs of documents to ingest. Mix of local:// and https:// is fine."
    }
  },
  "required": [
    "id",
    "doc_urls"
  ]
}

pcc_onboard_session_build_agent

Finalise a physical-operator onboarding session: registers the operator on PCC, mints a wallet, writes the SEO mirror, returns the publication payload (capabilities, operator_id, discovery_url). Idempotent — safe to retry inside the same session_id. Auth-required.

Parameters1

string

required

Session id returned by pcc_onboard_session_start.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Session id returned by pcc_onboard_session_start."
    }
  },
  "required": [
    "id"
  ]
}

pcc_onboard_session_status

Coarse status snapshot for a physical-operator onboarding session: current state, 0-100 progress, scraped_count, ingested_count, last_event, publication payload (if built). Cheap — designed for polling from the chat header. Auth-required.

Parameters1

string

required

Session id returned by pcc_onboard_session_start.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Session id returned by pcc_onboard_session_start."
    }
  },
  "required": [
    "id"
  ]
}

pcc_onboard_session_live_data

Full event log for a physical-operator onboarding session — feeds the chat console's activity sidebar. Supports incremental polling via ?since=<unix-millis>. Returns the next cursor on every response. Auth-required.

Parameters2

id	string	required	Session id returned by pcc_onboard_session_start.
since	number	optional	Unix milliseconds cursor — returns only events with t > since. Use the 'cursor' field of the previous response for incremental polling.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Session id returned by pcc_onboard_session_start."
    },
    "since": {
      "type": "number",
      "description": "Unix milliseconds cursor — returns only events with t > since. Use the 'cursor' field of the previous response for incremental polling."
    }
  },
  "required": [
    "id"
  ]
}

pcc_contributor_register

Register a contributor profile binding a wallet address to a role and a published RateSchedule. Body: address (0x40hex), role (10 ContributorRole values from ADR-12 §2.1 + legacy 'designer'), scheduleHash (0x64hex of a previously published schedule), optional ipId, metadataUri, contributorNftTokenId. Returns the persisted profile (composite id is address:role:tail). Idempotent on the composite id — re-posting the same (address, role, contributorNftTokenId) replaces the prior profile.

Parameters6

address	string	required	Wallet address (0x + 40 hex chars)
role	string	required	ContributorRole — 10 ADR-12 roles + deprecated 'designer'
scheduleHash	string	required	0x + 64 hex sha256 of a published RateSchedule
ipId	string	optional	Optional Story Protocol IP Asset ID
metadataUri	string	optional	Optional ipfs:// or https:// URI
contributorNftTokenId	string	optional	Optional ContributorNFT tokenId once minted on-chain

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Wallet address (0x + 40 hex chars)"
    },
    "role": {
      "type": "string",
      "enum": [
        "operator",
        "verifier",
        "insurer",
        "integrator",
        "protocol-author",
        "model-author",
        "dataset-contributor",
        "curator",
        "assembler",
        "network-treasury",
        "designer"
      ],
      "description": "ContributorRole — 10 ADR-12 roles + deprecated 'designer'"
    },
    "scheduleHash": {
      "type": "string",
      "description": "0x + 64 hex sha256 of a published RateSchedule"
    },
    "ipId": {
      "type": "string",
      "description": "Optional Story Protocol IP Asset ID"
    },
    "metadataUri": {
      "type": "string",
      "description": "Optional ipfs:// or https:// URI"
    },
    "contributorNftTokenId": {
      "type": "string",
      "description": "Optional ContributorNFT tokenId once minted on-chain"
    }
  },
  "required": [
    "address",
    "role",
    "scheduleHash"
  ]
}

pcc_contributor_list

List all contributor profiles for an address across roles. Returns an array of {id, address, role, scheduleHash, ipId, contributorNftTokenId, metadataUri, registeredAt}. Returns empty array when no profiles exist for the address.

Parameters1

address

string

required

Wallet address (0x + 40 hex chars)

Raw schema

{
  "type": "object",
  "properties": {
    "address": {
      "type": "string",
      "description": "Wallet address (0x + 40 hex chars)"
    }
  },
  "required": [
    "address"
  ]
}

pcc_schedule_publish

Publish a sealed off-chain RateSchedule. Computes scheduleHash server-side via the canonical sha256-over-canonical-JSON algorithm (matching the on-chain RateScheduleRegistry.publish() invariant). Idempotent: re-publishing the same content returns alreadyPublished:true. Returns {scheduleHash, alreadyPublished}.

Parameters2

publishedBy	string	required	Address that publishes (0x + 40 hex chars)
schedule	object	required	RateSchedule body — version, segments (constant/step/linear-decay/exponential-decay/adoption-indexed/piecewise-value), and optional notes

Raw schema

{
  "type": "object",
  "properties": {
    "publishedBy": {
      "type": "string",
      "description": "Address that publishes (0x + 40 hex chars)"
    },
    "schedule": {
      "type": "object",
      "description": "RateSchedule body — version, segments (constant/step/linear-decay/exponential-decay/adoption-indexed/piecewise-value), and optional notes",
      "properties": {
        "version": {
          "type": "integer",
          "minimum": 1
        },
        "segments": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "minItems": 1
        },
        "notes": {
          "type": "string"
        }
      },
      "required": [
        "version",
        "segments"
      ]
    }
  },
  "required": [
    "publishedBy",
    "schedule"
  ]
}

pcc_schedule_get

Fetch a published RateSchedule by its content hash. Returns {schedule, publishedBy} with segments re-validated via Zod, or 404 if not found.

Parameters1

scheduleHash

string

required

0x + 64 hex sha256 of the schedule

Raw schema

{
  "type": "object",
  "properties": {
    "scheduleHash": {
      "type": "string",
      "description": "0x + 64 hex sha256 of the schedule"
    }
  },
  "required": [
    "scheduleHash"
  ]
}

pcc_schedule_evaluate

Evaluate a published RateSchedule at a moment, returning the effective bps. Inputs: scheduleHash + now (unix seconds) + optional jobValueCents (piecewise-value) + optional jobsPerDay (adoption-indexed). Returns {scheduleHash, bps, segmentKind, segmentIndex}. segmentIndex=-1 + bps=0 when no segment covers the moment (silent gap).

Parameters4

scheduleHash	string	required	0x + 64 hex schedule hash
now	integer	required	Unix seconds at evaluation moment
jobValueCents	integer	optional	Job value in cents (piecewise-value segments)
jobsPerDay	number	optional	Rolling 24h job count (adoption-indexed segments)

Raw schema

{
  "type": "object",
  "properties": {
    "scheduleHash": {
      "type": "string",
      "description": "0x + 64 hex schedule hash"
    },
    "now": {
      "type": "integer",
      "minimum": 0,
      "description": "Unix seconds at evaluation moment"
    },
    "jobValueCents": {
      "type": "integer",
      "minimum": 0,
      "description": "Job value in cents (piecewise-value segments)"
    },
    "jobsPerDay": {
      "type": "number",
      "minimum": 0,
      "description": "Rolling 24h job count (adoption-indexed segments)"
    }
  },
  "required": [
    "scheduleHash",
    "now"
  ]
}

pcc_training_manifest_set

Set (insert-or-replace) the TrainingManifest for a model IP — the dataset weight map the LicensingEngine walks when distributing payouts to a 'model-author' entry in a CompositionManifest. Dataset weightBps must sum to ≤ 10000 (gateway accepts partial mixes; on-chain enforces exact 10000). Returns {modelIpId, manifestHash}.

Parameters4

modelIpId	string	required	Story IP Asset ID for the model
baseModelIpId	string	optional	Optional parent ModelNFT IP if this was fine-tuned
datasetWeights	array	required	DatasetIP entries with weightBps (sum ≤ 10000)
methodologyHash	string	optional	Optional 0x + 64 hex reproducibility hash

Raw schema

{
  "type": "object",
  "properties": {
    "modelIpId": {
      "type": "string",
      "description": "Story IP Asset ID for the model"
    },
    "baseModelIpId": {
      "type": "string",
      "description": "Optional parent ModelNFT IP if this was fine-tuned"
    },
    "datasetWeights": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "datasetIpId": {
            "type": "string"
          },
          "weightBps": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "dataPointCount": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "datasetIpId",
          "weightBps"
        ]
      },
      "description": "DatasetIP entries with weightBps (sum ≤ 10000)"
    },
    "methodologyHash": {
      "type": "string",
      "description": "Optional 0x + 64 hex reproducibility hash"
    }
  },
  "required": [
    "modelIpId",
    "datasetWeights"
  ]
}

pcc_training_manifest_get

Fetch the TrainingManifest for a model IP. Returns the parsed datasets array + manifestHash + createdAt, or 404 if no manifest has been set.

Parameters1

modelIpId

string

required

Story IP Asset ID for the model

Raw schema

{
  "type": "object",
  "properties": {
    "modelIpId": {
      "type": "string",
      "description": "Story IP Asset ID for the model"
    }
  },
  "required": [
    "modelIpId"
  ]
}

pcc_trilobio_build_config

Generate a complete KERNEL_CONFIG JSON for a Trilobio (tcode-api) fleet controller. Wraps `buildTrilobioConfig()` from the @pcc/trilobio npm package. Returns a TrilobioKernelConfig with sensible defaults (pollIntervalMs=3000, maxScriptTimeoutSec=3600, allowArbitraryScripts=false). The result can be passed to `pcc-node start` via the KERNEL_CONFIG env var, or handed to setup_generate_config / setup_register_device for direct API-driven registration. Note: this is a TypeScript package helper (no HTTP call). For programmatic use, `import { buildTrilobioConfig } from "@pcc/trilobio"`.

Parameters12

url	string	required	Fleet-controller URL on the LAN (host[:port], no trailing slash, no path) — e.g. http://192.168.1.50
apiKey	string	optional	Trilobio fleet-controller API key (from the trilobot admin UI). Either apiKey OR username+password is required unless mockMode=true.
username	string	optional	Fleet-controller account username (basic-auth mode only)
password	string	optional	Fleet-controller account password (basic-auth mode only)
kernelId	string	optional	Kernel ID this device belongs to (auto-generated as kernel_trilobio_<timestamp> if omitted)
deviceId	string	optional	Logical device ID within the kernel (default: trilobio-fleet-01)
tcodeApiVersion	string	optional	Pinned tcode-api version on the fleet controller. Format: 'latest' or semver (e.g. 1.25.1). Default: latest. Surfaces in evidence bundles for reproducibility.
mockMode	boolean	optional	Bypass real HTTP and simulate runs. Use for CI / floor demos. Default: false.
pollIntervalMs	number	optional	Poll interval in ms for run status (range 500-60000). Default: 3000.
maxScriptTimeoutSec	number	optional	Maximum allowed wall-clock seconds for a single tcode script (range 30-86400). Default: 3600.
mockRunDurationMs	number	optional	Mock-mode simulated run duration in ms. Default: 2000.
allowArbitraryScripts	boolean	optional	Permit customer-supplied tcode-api Python scripts (true) or only curated protocol IDs (false). Default: false. Set true only for trusted-counterparty deployments.

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Fleet-controller URL on the LAN (host[:port], no trailing slash, no path) — e.g. http://192.168.1.50"
    },
    "apiKey": {
      "type": "string",
      "description": "Trilobio fleet-controller API key (from the trilobot admin UI). Either apiKey OR username+password is required unless mockMode=true."
    },
    "username": {
      "type": "string",
      "description": "Fleet-controller account username (basic-auth mode only)"
    },
    "password": {
      "type": "string",
      "description": "Fleet-controller account password (basic-auth mode only)"
    },
    "kernelId": {
      "type": "string",
      "description": "Kernel ID this device belongs to (auto-generated as kernel_trilobio_<timestamp> if omitted)"
    },
    "deviceId": {
      "type": "string",
      "description": "Logical device ID within the kernel (default: trilobio-fleet-01)"
    },
    "tcodeApiVersion": {
      "type": "string",
      "description": "Pinned tcode-api version on the fleet controller. Format: 'latest' or semver (e.g. 1.25.1). Default: latest. Surfaces in evidence bundles for reproducibility."
    },
    "mockMode": {
      "type": "boolean",
      "description": "Bypass real HTTP and simulate runs. Use for CI / floor demos. Default: false."
    },
    "pollIntervalMs": {
      "type": "number",
      "description": "Poll interval in ms for run status (range 500-60000). Default: 3000."
    },
    "maxScriptTimeoutSec": {
      "type": "number",
      "description": "Maximum allowed wall-clock seconds for a single tcode script (range 30-86400). Default: 3600."
    },
    "mockRunDurationMs": {
      "type": "number",
      "description": "Mock-mode simulated run duration in ms. Default: 2000."
    },
    "allowArbitraryScripts": {
      "type": "boolean",
      "description": "Permit customer-supplied tcode-api Python scripts (true) or only curated protocol IDs (false). Default: false. Set true only for trusted-counterparty deployments."
    }
  },
  "required": [
    "url"
  ]
}

pcc_trilobio_validate_options

Sanity-check operator-supplied Trilobio options before generating a KERNEL_CONFIG. Wraps `validateTrilobioOptions()` from @pcc/trilobio. Catches the common mistakes (malformed URL, missing creds, out-of-range timeouts, invalid tcodeApiVersion semver) before they hit the gateway or the device. Returns { valid: boolean, errors: string[], warnings?: string[] }. Note: this is a TypeScript package helper (no HTTP call); for programmatic use, `import { validateTrilobioOptions } from "@pcc/trilobio"`.

Parameters12

url	string	optional	Fleet-controller URL
apiKey	string	optional	Fleet-controller API key
username	string	optional	Basic-auth username
password	string	optional	Basic-auth password
kernelId	string	optional
deviceId	string	optional
tcodeApiVersion	string	optional	'latest' or semver string
mockMode	boolean	optional
pollIntervalMs	number	optional
maxScriptTimeoutSec	number	optional
mockRunDurationMs	number	optional
allowArbitraryScripts	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Fleet-controller URL"
    },
    "apiKey": {
      "type": "string",
      "description": "Fleet-controller API key"
    },
    "username": {
      "type": "string",
      "description": "Basic-auth username"
    },
    "password": {
      "type": "string",
      "description": "Basic-auth password"
    },
    "kernelId": {
      "type": "string"
    },
    "deviceId": {
      "type": "string"
    },
    "tcodeApiVersion": {
      "type": "string",
      "description": "'latest' or semver string"
    },
    "mockMode": {
      "type": "boolean"
    },
    "pollIntervalMs": {
      "type": "number"
    },
    "maxScriptTimeoutSec": {
      "type": "number"
    },
    "mockRunDurationMs": {
      "type": "number"
    },
    "allowArbitraryScripts": {
      "type": "boolean"
    }
  },
  "required": []
}

pcc_trilobio_validate_script

Quick lint of a tcode-api Python script before submission to a Trilobio fleet controller. Wraps `validateTcodeScript()` from @pcc/trilobio. Surface check only — NOT a sandbox or sanitizer. Looks for: imports of `tcode_api` (presence required), obviously dangerous statements (subprocess, os.system, eval, exec, __import__, socket, urllib, requests, file writes), empty scripts, and missing top-level tcode commands. Returns { valid: boolean, errors: string[], warnings?: string[] }. Operators with `allowArbitraryScripts=true` should treat results as a hint — the fleet controller is the source of truth on safety. Note: TypeScript package helper (no HTTP call); for programmatic use, `import { validateTcodeScript } from "@pcc/trilobio"`.

Parameters1

source

string

required

Full Python source of the tcode-api script to lint

Raw schema

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "Full Python source of the tcode-api script to lint"
    }
  },
  "required": [
    "source"
  ]
}

pcc_trilobio_capability_template

Return the `TRILOBIO_CAPABILITY` constant from @pcc/trilobio — a default capability template for a Trilobio fleet controller. Pass to POST /api/capabilities to publish a baseline liquid-handling capability for a kernel hosting a trilobot. Operators can extend the `materials` and `capabilities` arrays to advertise instrument-specific features (custom labware libraries, sample types). Notable: includes `tcode-script-execution` as an advertised capability, which is unique to Trilobio — operators who set `allowArbitraryScripts: true` can accept jobs that ship a full tcode-api Python script as the protocol payload. Note: TypeScript package helper (no HTTP call); for programmatic use, `import { TRILOBIO_CAPABILITY } from "@pcc/trilobio"`.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

attach_operator_channel

Attach a notification/dispatch channel to an operator so PCC knows how to ping them when a job lands. The operator's onboarding agent calls this AFTER the conversation that produced the channel record. Transport is a small stable enum (webhook|email|sms|voice|push|mqtt|file|manual) — vendor specifics live in the free-form `describe` field, written by the operator's agent. PCC the substrate stays neutral. Returns the channel record with a generated id.

Parameters9

slug	string	required	Operator slug (typically the operator's address or unique identifier).
label	string	required	Short human label shown to the operator and in admin UIs: 'Front counter printer', 'Owner's phone'.
transport	string	required	Which wire does the message go over. `manual` = no machine endpoint (dashboard-only).
direction	string	optional	out=PCC pushes only; in-out=operator's system also replies; in=operator pushes unsolicited.
endpoint	object	optional	Transport-specific routing payload. webhook→{url}, email→{address}, sms/voice→{phoneE164}, push→{token,platform}, mqtt→{brokerUrl,topic}, file→{scheme,path}, manual→{}.
credentialRef	string	optional	Reference to a secret in the credential vault (not the secret itself). PCC resolves it at dispatch time.
describe	string	required	Plain-English instructions for how PCC should talk to whatever is on the other end. Written by the operator's onboarding agent. Required, ≥4 chars. Example: 'POST JSON with keys order_id, line_items[], deadline_iso. I will POST back {order_id, status} to your reply URL.'
replyContract	string	optional	Optional operator-authored contract describing how the operator's system will respond to evidence requests, status pings, etc.
enabled	boolean	optional	Whether the channel is live (defaults to true).

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Operator slug (typically the operator's address or unique identifier)."
    },
    "label": {
      "type": "string",
      "description": "Short human label shown to the operator and in admin UIs: 'Front counter printer', 'Owner's phone'."
    },
    "transport": {
      "type": "string",
      "enum": [
        "webhook",
        "email",
        "sms",
        "voice",
        "push",
        "mqtt",
        "file",
        "manual"
      ],
      "description": "Which wire does the message go over. `manual` = no machine endpoint (dashboard-only)."
    },
    "direction": {
      "type": "string",
      "enum": [
        "out",
        "in-out",
        "in"
      ],
      "description": "out=PCC pushes only; in-out=operator's system also replies; in=operator pushes unsolicited."
    },
    "endpoint": {
      "type": "object",
      "description": "Transport-specific routing payload. webhook→{url}, email→{address}, sms/voice→{phoneE164}, push→{token,platform}, mqtt→{brokerUrl,topic}, file→{scheme,path}, manual→{}."
    },
    "credentialRef": {
      "type": "string",
      "description": "Reference to a secret in the credential vault (not the secret itself). PCC resolves it at dispatch time."
    },
    "describe": {
      "type": "string",
      "description": "Plain-English instructions for how PCC should talk to whatever is on the other end. Written by the operator's onboarding agent. Required, ≥4 chars. Example: 'POST JSON with keys order_id, line_items[], deadline_iso. I will POST back {order_id, status} to your reply URL.'"
    },
    "replyContract": {
      "type": "string",
      "description": "Optional operator-authored contract describing how the operator's system will respond to evidence requests, status pings, etc."
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether the channel is live (defaults to true)."
    }
  },
  "required": [
    "slug",
    "label",
    "transport",
    "describe"
  ]
}

list_operator_channels

List every channel attached to an operator. Returns the full channel records (id, transport, direction, endpoint, describe, enabled flags). Useful for an operator's onboarding agent to confirm what is wired up, and for status dashboards.

Parameters1

slug

string

required

Operator slug.

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Operator slug."
    }
  },
  "required": [
    "slug"
  ]
}

update_operator_channel

Update an existing channel — toggle enabled, rewrite the describe contract, change the endpoint payload, etc. Merges into the existing record. The operator slug, id, and createdAt are immutable.

Parameters8

id	string	required	Channel id (returned from attach_operator_channel).
label	string	optional
direction	string	optional
endpoint	object	optional
credentialRef	string	optional
describe	string	optional
replyContract	string	optional
enabled	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Channel id (returned from attach_operator_channel)."
    },
    "label": {
      "type": "string"
    },
    "direction": {
      "type": "string",
      "enum": [
        "out",
        "in-out",
        "in"
      ]
    },
    "endpoint": {
      "type": "object"
    },
    "credentialRef": {
      "type": "string"
    },
    "describe": {
      "type": "string"
    },
    "replyContract": {
      "type": "string"
    },
    "enabled": {
      "type": "boolean"
    }
  },
  "required": [
    "id"
  ]
}

delete_operator_channel

Remove a channel from an operator. Future jobs will not dispatch to it. Use update_operator_channel with enabled=false to silence temporarily without losing the recipe in `describe`.

Parameters1

string

required

Channel id.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Channel id."
    }
  },
  "required": [
    "id"
  ]
}

test_operator_channels

Fire a synthetic job at every enabled channel for an operator so the onboarding agent (and the human watching) can confirm the integration end-to-end before a real job lands. Returns per-channel dispatch results (delivered, ref, warnings).

Parameters1

slug

string

required

Operator slug.

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Operator slug."
    }
  },
  "required": [
    "slug"
  ]
}

suggest_csd_templates

Bidirectional onboarding: the registry talks back. Describe in plain English what you are trying to set up — 'wood-fired pizza shop in SF', 'Opentrons OT-2 liquid handler', 'same-day SF courier' — and the registry returns N candidate Capability StructureDefinition (CSD) templates ranked by keyword-overlap relevance (name×3, tags×2, description×1; tie-break on usage). Empty query falls back to popularity-ordered top picks. After picking one, pass the chosen type to pcc-author-integration. Score-zero results are dropped.

Parameters3

q	string	optional	Plain-English description of the capability the user is trying to set up. Optional — empty falls back to popularity.
limit	integer	optional	Max results (1..20, default 5).
kind	string	optional	Filter by CSD kind.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "Plain-English description of the capability the user is trying to set up. Optional — empty falls back to popularity."
    },
    "limit": {
      "type": "integer",
      "description": "Max results (1..20, default 5).",
      "minimum": 1,
      "maximum": 20
    },
    "kind": {
      "type": "string",
      "enum": [
        "base",
        "profile",
        "extension",
        "workflow"
      ],
      "description": "Filter by CSD kind."
    }
  },
  "required": []
}

get_popular_csd_templates

Return CSDs sorted by adoption (usage-count descending). Useful for first-time operators who want to see what kind of capabilities others are publishing. Each entry includes the CSD record plus usage attribution: count, recent adopters (deduped, capped at 50), and lastUsedAt.

Parameters1

limit

integer

optional

Max results (1..50, default 10).

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Max results (1..50, default 10).",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": []
}

get_operator_status

Four-slot substrate view for an operator: kernels, capabilities (with sla + availability), notification channels, and the per-kernel A2A agent-card URLs. Returns totals and a `missing` list naming any of the four onboarding slots that are still empty. Use this from an onboarding agent's wrap-up step to confirm 'are all four slots wired before I go live?' status is `ready` | `partial` | `unconfigured`. Public — operator slug is non-secret and the response carries no credentials (channel `credentialRef` values are vault references, not secrets).

Parameters1

slug

string

required

Operator slug — typically the operator's wallet address used as `operatorAddress` on their kernels.

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Operator slug — typically the operator's wallet address used as `operatorAddress` on their kernels."
    }
  },
  "required": [
    "slug"
  ]
}

propose_composition

Propose a composition — a sequenced DAG of capability instances to satisfy a multi-step outcome under a budget + assurance tier. Accepts either a flat `steps` list or an outcome chain. Returns a candidate plan ranked by `optimizeFor` (price | speed | quality) with per-step assignments. The composition is persisted for ~30 minutes (proposed status) and can be executed once via execute_composition.

Parameters9

outcomeType	string	required	High-level outcome label, ≤120 chars. Example: 'desk-robot-prototype'.
steps	array	optional	Ordered list of capability types this composition needs (1..20). Use this OR `outcomeChain`.
outcomeChain	array	optional	Alternative to `steps`: chain of named sub-outcomes. The planner expands each into capability types.
budgetUSD	number	required	Total budget the user is willing to spend across all steps.
minAssuranceTier	integer	required	Minimum acceptable assurance tier on every step.
location	object	optional	Geographic constraint (lat/lng + radius, or country, etc).
optimizeFor	string	optional	Ranking objective (default `price`).
requester	object	optional	{agentId, did?} — the agent submitting the request.
description	string	optional	Free-form natural-language description (≤4000 chars).

Raw schema

{
  "type": "object",
  "properties": {
    "outcomeType": {
      "type": "string",
      "description": "High-level outcome label, ≤120 chars. Example: 'desk-robot-prototype'."
    },
    "steps": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ordered list of capability types this composition needs (1..20). Use this OR `outcomeChain`."
    },
    "outcomeChain": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Alternative to `steps`: chain of named sub-outcomes. The planner expands each into capability types."
    },
    "budgetUSD": {
      "type": "number",
      "description": "Total budget the user is willing to spend across all steps."
    },
    "minAssuranceTier": {
      "type": "integer",
      "enum": [
        0,
        1,
        2,
        3
      ],
      "description": "Minimum acceptable assurance tier on every step."
    },
    "location": {
      "type": "object",
      "description": "Geographic constraint (lat/lng + radius, or country, etc)."
    },
    "optimizeFor": {
      "type": "string",
      "enum": [
        "price",
        "speed",
        "quality"
      ],
      "description": "Ranking objective (default `price`)."
    },
    "requester": {
      "type": "object",
      "description": "{agentId, did?} — the agent submitting the request."
    },
    "description": {
      "type": "string",
      "description": "Free-form natural-language description (≤4000 chars)."
    }
  },
  "required": [
    "outcomeType",
    "budgetUSD",
    "minAssuranceTier"
  ]
}

get_composition

Retrieve a previously-proposed composition by id. Returns 404 if unknown, 410 if the 30-minute proposal window has expired. Use this to inspect a plan before executing, or to recover a plan id after a restart.

Parameters1

string

required

Composition id (returned from propose_composition).

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Composition id (returned from propose_composition)."
    }
  },
  "required": [
    "id"
  ]
}

execute_composition

Commit a proposed composition: drives the DAG through the workflow engine, each step records a reputation outcome, the composition's reputation is finalized when the run ends. When `PCC_COMPOSE_EXECUTE_REAL=true` is set on the gateway, steps submit real jobs via JobFacade and the workflow run is durable (@pcc/workflow). When the flag is off, the NOOP runner returns synthetic success — useful in dev/test. Re-executing an already-run composition replays the stored result (idempotent — reputation deltas are applied exactly once).

Parameters2

id	string	required	Composition id from propose_composition. Must be in `proposed` status and not expired.
idempotencyKey	string	optional	Optional caller-supplied key (≤120 chars) to dedupe execute calls.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Composition id from propose_composition. Must be in `proposed` status and not expired."
    },
    "idempotencyKey": {
      "type": "string",
      "description": "Optional caller-supplied key (≤120 chars) to dedupe execute calls."
    }
  },
  "required": [
    "id"
  ]
}

pcc_report

Report friction, confusion, or bugs you hit while onboarding. Call this when you get stuck and cannot recover from an error, when a tool description was misleading, when an endpoint returned an unexplained 500, or when you abandoned a workflow because the next step was unclear. Include your `trace_id` (returned from `provision_api_key` or echoed via the `x-pcc-trace-id` response header) so PCC operators can replay your full journey. PUBLIC — works even before you provision an API key. Rate-limited (30 reports/hour/IP) to limit spam.

Parameters7

trace_id	string	optional	Your onboarding journey ID. Returned by provision_api_key (body field) and present on every response as the `x-pcc-trace-id` header.
summary	string	required	1-line description of what went wrong. Example: 'Build options endpoint returned 500 with no hint about what was missing.'
detail	string	optional	Multi-line context: full error code, what you tried, what you expected. Optional but recommended.
last_endpoint	string	optional	The route you were on when you got stuck. Example: '/api/build/contract'.
last_error_code	string	optional	The error code from the Result<T> envelope you received, if any. Example: 'BAD_REQUEST', 'CAPABILITY_NOT_FOUND'.
agent_kind	string	optional	Which model / agent you are. Example: 'claude', 'gpt-4o', 'gemini', 'canary'.
confused_about	string	optional	Free-form category — which onboarding stage tripped you up. Example: 'auth', 'discovery', 'build', 'fund', 'submit', 'settle'.

Raw schema

{
  "type": "object",
  "properties": {
    "trace_id": {
      "type": "string",
      "pattern": "^tr_[0-9a-f]{16,32}$",
      "description": "Your onboarding journey ID. Returned by provision_api_key (body field) and present on every response as the `x-pcc-trace-id` header."
    },
    "summary": {
      "type": "string",
      "minLength": 4,
      "maxLength": 280,
      "description": "1-line description of what went wrong. Example: 'Build options endpoint returned 500 with no hint about what was missing.'"
    },
    "detail": {
      "type": "string",
      "maxLength": 4000,
      "description": "Multi-line context: full error code, what you tried, what you expected. Optional but recommended."
    },
    "last_endpoint": {
      "type": "string",
      "maxLength": 200,
      "description": "The route you were on when you got stuck. Example: '/api/build/contract'."
    },
    "last_error_code": {
      "type": "string",
      "maxLength": 200,
      "description": "The error code from the Result<T> envelope you received, if any. Example: 'BAD_REQUEST', 'CAPABILITY_NOT_FOUND'."
    },
    "agent_kind": {
      "type": "string",
      "maxLength": 200,
      "description": "Which model / agent you are. Example: 'claude', 'gpt-4o', 'gemini', 'canary'."
    },
    "confused_about": {
      "type": "string",
      "maxLength": 200,
      "description": "Free-form category — which onboarding stage tripped you up. Example: 'auth', 'discovery', 'build', 'fund', 'submit', 'settle'."
    }
  },
  "required": [
    "summary"
  ]
}

save_dashboard

Save a generated dashboard to the network so the user gets a live, shareable URL: https://capability.network/a/<slug>. Pass a `manifest` — a small declarative DashboardManifest (windows + live-data bindings + actions) conforming to the schema at https://capability.network/ui-kit/v1/manifest.schema.json; the shipped pcc-ui kit renders it identically everywhere (you compose the manifest, the kit renders it — never hand-rolled HTML). WHEN to call this: only when the task needs a surface to watch/approve/compare/reuse (a live job, a value chain, a settlement trail, a recurring order) — never for a one-line answer. RECALL FIRST: call search_dashboards before generating; reload or fork a match instead of duplicating. The manifest MUST NOT contain an API key (a shared artifact travels with its contents — the network rejects one that does). Returns the stored artifact incl. its slug. Defaults visibility to 'unlisted' (link-shareable, not listed).

Parameters7

name	string	required	Short human name for the dashboard, e.g. 'Watch my pizza + courier'. Used to mint the slug.
description	string	optional	One-line description of what the dashboard shows.
manifest	object	required	The DashboardManifest (2-6KB JSON) conforming to https://capability.network/ui-kit/v1/manifest.schema.json. Required top-level keys: `csd` (must be 'pcc://artifacts/dashboard/v1'), `title`, and `sections[]` (each section has `windows[]`). Window kinds: note, metric, capability, list, form, run, approval, receipt, chain, actions. Bindings point at live routes you already use (/api/jobs/:id, /api/escrow/:id, /sse/stream/job/:id). No API key anywhere in the manifest.
capabilityTypes	array	optional	Capability types this dashboard is about, e.g. ['pizza.order','courier.dispatch']. This is the discovery join — it's how search_dashboards finds this artifact later.
composeRefs	array	optional	Optional pinned, re-plannable ComposeRequest objects (value chains). Pin the request, never a compositionId (those expire in 30 min).
visibility	string	optional	Who can load it. Default 'unlisted' (anyone with the link; not in listings). 'public' appears in search_dashboards; 'private' is owner-only.
renderedCid	string	optional	Optional CID of a rendered-HTML export saved via /api/storage.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Short human name for the dashboard, e.g. 'Watch my pizza + courier'. Used to mint the slug."
    },
    "description": {
      "type": "string",
      "description": "One-line description of what the dashboard shows."
    },
    "manifest": {
      "type": "object",
      "description": "The DashboardManifest (2-6KB JSON) conforming to https://capability.network/ui-kit/v1/manifest.schema.json. Required top-level keys: `csd` (must be 'pcc://artifacts/dashboard/v1'), `title`, and `sections[]` (each section has `windows[]`). Window kinds: note, metric, capability, list, form, run, approval, receipt, chain, actions. Bindings point at live routes you already use (/api/jobs/:id, /api/escrow/:id, /sse/stream/job/:id). No API key anywhere in the manifest."
    },
    "capabilityTypes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Capability types this dashboard is about, e.g. ['pizza.order','courier.dispatch']. This is the discovery join — it's how search_dashboards finds this artifact later."
    },
    "composeRefs": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Optional pinned, re-plannable ComposeRequest objects (value chains). Pin the request, never a compositionId (those expire in 30 min)."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ],
      "description": "Who can load it. Default 'unlisted' (anyone with the link; not in listings). 'public' appears in search_dashboards; 'private' is owner-only."
    },
    "renderedCid": {
      "type": "string",
      "description": "Optional CID of a rendered-HTML export saved via /api/storage."
    }
  },
  "required": [
    "name",
    "manifest"
  ]
}

get_dashboard

Recall a saved dashboard by its id or slug. Returns the full artifact (manifest + metadata). Use this to reload a dashboard the user asks for again ('open my pizza dashboard') instead of regenerating it — a saved dashboard reloads with zero regeneration. Public for public/unlisted artifacts; owner-only for private ones. Increments the load counter (a popularity signal).

Parameters1

idOrSlug

string

required

The artifact id (ua_...) or its slug (e.g. 'watch-my-pizza-8k3f', the tail of the /a/<slug> URL).

Raw schema

{
  "type": "object",
  "properties": {
    "idOrSlug": {
      "type": "string",
      "description": "The artifact id (ua_...) or its slug (e.g. 'watch-my-pizza-8k3f', the tail of the /a/<slug> URL)."
    }
  },
  "required": [
    "idOrSlug"
  ]
}

search_dashboards

Discover existing public dashboards before you generate a new one (recall-first — the library accrues; adopt > extend > build for UIs too). Filter by `capabilityType` (e.g. 'pizza.order'), free-text `q` over name/description/types, and `sort` by popularity or recency. Returns { entries, total, offset, limit }. Only public artifacts are listed; unlisted ones load by slug via get_dashboard but never appear here.

Parameters5

capabilityType	string	optional	Filter to dashboards tagged with this capability type, e.g. 'pizza.order'.
q	string	optional	Free-text search over name, description, and capability types.
sort	string	optional	Ranking: 'popular' (by use+load+fork counts) or 'recent' (default).
offset	integer	optional	Pagination offset (default 0).
limit	integer	optional	Max results (1..100, default 20).

Raw schema

{
  "type": "object",
  "properties": {
    "capabilityType": {
      "type": "string",
      "description": "Filter to dashboards tagged with this capability type, e.g. 'pizza.order'."
    },
    "q": {
      "type": "string",
      "description": "Free-text search over name, description, and capability types."
    },
    "sort": {
      "type": "string",
      "enum": [
        "popular",
        "recent"
      ],
      "description": "Ranking: 'popular' (by use+load+fork counts) or 'recent' (default)."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "description": "Pagination offset (default 0)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Max results (1..100, default 20)."
    }
  },
  "required": []
}

fork_dashboard

Fork an existing dashboard into a new artifact you own, preserving lineage back to the original (the social remix verb). Use this to adapt a popular dashboard rather than build from scratch — e.g. fork a 'watch pizza' dashboard and raise the budget or add a receipt window via update_dashboard. Increments the source's fork counter. You can fork any public/unlisted artifact, or a private one you own.

Parameters3

id	string	required	The id (ua_...) of the artifact to fork.
name	string	optional	Optional name for the fork (defaults to '<original> (fork)').
visibility	string	optional	Visibility of the fork (default 'unlisted').

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The id (ua_...) of the artifact to fork."
    },
    "name": {
      "type": "string",
      "description": "Optional name for the fork (defaults to '<original> (fork)')."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ],
      "description": "Visibility of the fork (default 'unlisted')."
    }
  },
  "required": [
    "id"
  ]
}

update_dashboard

Modify a dashboard you own (owner-only). Replace the manifest or any metadata field; the version increments. Use this to edit a saved surface meaningfully — 'raise budgetUSD to 40', 'add a receipt window', 'make it public'. A replaced manifest must still conform to the schema and must not contain an API key. Only send the fields you want to change.

Parameters8

id	string	required	The id (ua_...) of the artifact to update.
name	string	optional	New name.
description	string	optional	New description.
manifest	object	optional	Replacement DashboardManifest (must conform to the schema; no API key). Omit to leave the manifest unchanged.
capabilityTypes	array	optional	Replacement capability-type tags.
composeRefs	array	optional	Replacement pinned ComposeRequest objects.
visibility	string	optional	New visibility (e.g. flip 'unlisted' -> 'public' to list it).
renderedCid	string	optional	New rendered-HTML export CID.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The id (ua_...) of the artifact to update."
    },
    "name": {
      "type": "string",
      "description": "New name."
    },
    "description": {
      "type": "string",
      "description": "New description."
    },
    "manifest": {
      "type": "object",
      "description": "Replacement DashboardManifest (must conform to the schema; no API key). Omit to leave the manifest unchanged."
    },
    "capabilityTypes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Replacement capability-type tags."
    },
    "composeRefs": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Replacement pinned ComposeRequest objects."
    },
    "visibility": {
      "type": "string",
      "enum": [
        "private",
        "unlisted",
        "public"
      ],
      "description": "New visibility (e.g. flip 'unlisted' -> 'public' to list it)."
    },
    "renderedCid": {
      "type": "string",
      "description": "New rendered-HTML export CID."
    }
  },
  "required": [
    "id"
  ]
}

render_pcc_dashboard

Compose a live PCC dashboard for a physical-capability task — pass a DashboardManifest (windows + live data bindings + actions) and it renders as an interactive MCP App.

Parameters6

csd	any	required	The builtin CSD URI this manifest conforms to.
title	string	required
description	string	optional
api_base	string	optional	Gateway base URL. Default https://capability.network.
theme	enum	optional
sections	array	required

Raw schema

{
  "type": "object",
  "properties": {
    "csd": {
      "const": "pcc://artifacts/dashboard/v1",
      "description": "The builtin CSD URI this manifest conforms to."
    },
    "title": {
      "type": "string",
      "minLength": 1
    },
    "description": {
      "type": "string"
    },
    "api_base": {
      "type": "string",
      "description": "Gateway base URL. Default https://capability.network."
    },
    "theme": {
      "enum": [
        "auto",
        "dark",
        "light"
      ]
    },
    "sections": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Section"
      }
    }
  },
  "required": [
    "csd",
    "title",
    "sections"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://capability.network/ui-kit/v1/manifest.schema.json",
  "title": "PCC Dashboard Manifest",
  "description": "JSON-Schema mirror of @pcc/spec DashboardManifestSchema (packages/spec/src/types/ui-artifact.ts). The small declarative dashboard a person's LLM emits; the pcc-ui kit renders it. Windows are a closed set rendered textContent-only. Actions never carry confirm:\"none\" (a human click is the confirm step). A manifest must NOT contain an API key (pcc_live_/pcc_test_) anywhere — a shared artifact travels with its contents.",
  "additionalProperties": false,
  "definitions": {
    "Binding": {
      "type": "object",
      "required": [
        "path"
      ],
      "additionalProperties": false,
      "description": "A live-data binding: which route a window reads, how often, what to pluck.",
      "properties": {
        "path": {
          "type": "string",
          "minLength": 1,
          "description": "'/api/…' route the window reads."
        },
        "query": {
          "type": "object",
          "description": "Query params merged onto the request."
        },
        "pollMs": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "description": "Poll cadence in ms (default ~30000)."
        },
        "sse": {
          "type": "string",
          "minLength": 1,
          "description": "SSE stream '/sse/stream/…' (fetch-SSE with Bearer)."
        },
        "select": {
          "type": "string",
          "description": "Dot-path into the response (e.g. 'data.jobs.0.status'). NOT JSONPath."
        }
      }
    },
    "Action": {
      "type": "object",
      "required": [
        "id",
        "label",
        "kind",
        "path",
        "confirm",
        "intentText"
      ],
      "additionalProperties": false,
      "description": "A write the surface can perform. Fires ONLY on a human click; nothing on load. confirm has NO 'none'. Money verbs use confirm:'approval'.",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "label": {
          "type": "string",
          "minLength": 1
        },
        "kind": {
          "enum": [
            "post",
            "patch"
          ]
        },
        "path": {
          "type": "string",
          "minLength": 1
        },
        "bodyFrom": {
          "type": "string",
          "description": "Form id whose collected values become the request body."
        },
        "body": {
          "type": "object",
          "description": "Static body merged into the request."
        },
        "confirm": {
          "enum": [
            "inline",
            "approval"
          ],
          "description": "'inline' = button confirm; 'approval' = the kit's Approval window. NO 'none'."
        },
        "idempotencyFrom": {
          "type": "string",
          "description": "Field id supplying an idempotencyKey (required on offer-posting actions)."
        },
        "intentText": {
          "type": "string",
          "minLength": 1,
          "description": "Snapshot-mode chip text handed to the LLM (e.g. 'pcc: approve offer …')."
        }
      }
    },
    "ListItem": {
      "type": "object",
      "required": [
        "title"
      ],
      "additionalProperties": false,
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "description": "Dot-path field for each row's title."
        },
        "meta": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "Dot-path fields for the row's meta line."
        },
        "statusFrom": {
          "type": "string",
          "description": "Dot-path field for the row's status pill."
        }
      }
    },
    "ComposeRequest": {
      "type": "object",
      "required": [
        "outcomeType",
        "budgetUSD",
        "minAssuranceTier"
      ],
      "additionalProperties": false,
      "description": "A re-plannable value-chain request (mirrors @pcc/spec ComposeRequestSchema). Pinned in a chain window, never a compositionId (30-min TTL).",
      "properties": {
        "outcomeType": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "steps": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "minItems": 1,
          "maxItems": 20
        },
        "outcomeChain": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "minItems": 1,
          "maxItems": 20
        },
        "budgetUSD": {
          "type": "number",
          "exclusiveMinimum": 0,
          "maximum": 1000000000
        },
        "minAssuranceTier": {
          "enum": [
            0,
            1,
            2,
            3
          ]
        },
        "location": {
          "type": "object",
          "required": [
            "lat",
            "lng"
          ],
          "additionalProperties": false,
          "properties": {
            "lat": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "lng": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            },
            "radiusKm": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 20000
            }
          }
        },
        "optimizeFor": {
          "enum": [
            "price",
            "speed",
            "quality"
          ]
        },
        "requester": {
          "type": "object",
          "required": [
            "agentId"
          ],
          "additionalProperties": false,
          "properties": {
            "agentId": {
              "type": "string",
              "minLength": 1
            },
            "did": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        "description": {
          "type": "string",
          "minLength": 1,
          "maxLength": 4000
        }
      }
    },
    "Section": {
      "type": "object",
      "required": [
        "windows"
      ],
      "additionalProperties": false,
      "properties": {
        "heading": {
          "type": "string"
        },
        "windows": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Window"
          }
        }
      }
    },
    "Window": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "kind",
            "text"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "note"
            },
            "text": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind",
            "label",
            "binding"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "metric"
            },
            "label": {
              "type": "string",
              "minLength": 1
            },
            "binding": {
              "$ref": "#/definitions/Binding"
            },
            "select": {
              "type": "string"
            },
            "format": {
              "enum": [
                "usd",
                "int",
                "pct",
                "ts"
              ]
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind",
            "binding"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "capability"
            },
            "binding": {
              "$ref": "#/definitions/Binding"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind",
            "binding",
            "item"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "list"
            },
            "binding": {
              "$ref": "#/definitions/Binding"
            },
            "item": {
              "$ref": "#/definitions/ListItem"
            },
            "limit": {
              "type": "integer",
              "exclusiveMinimum": 0
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind",
            "schema",
            "submit"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "form"
            },
            "schema": {
              "type": "object",
              "description": "A JSON Schema whose properties become form fields."
            },
            "submit": {
              "$ref": "#/definitions/Action"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind",
            "binding",
            "statusFrom",
            "latestFrom"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "run"
            },
            "binding": {
              "$ref": "#/definitions/Binding"
            },
            "statusFrom": {
              "type": "string"
            },
            "latestFrom": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind",
            "binding",
            "approve"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "approval"
            },
            "binding": {
              "$ref": "#/definitions/Binding"
            },
            "approve": {
              "$ref": "#/definitions/Action"
            },
            "deny": {
              "$ref": "#/definitions/Action"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind",
            "binding"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "receipt"
            },
            "binding": {
              "$ref": "#/definitions/Binding"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind",
            "composeRef"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "chain"
            },
            "composeRef": {
              "$ref": "#/definitions/ComposeRequest"
            },
            "execute": {
              "$ref": "#/definitions/Action"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "kind",
            "actions"
          ],
          "additionalProperties": false,
          "properties": {
            "kind": {
              "const": "actions"
            },
            "actions": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/definitions/Action"
              }
            }
          }
        }
      ]
    }
  }
}

README.md12 KBView on GitHub

Physical Capability Cloud (PCC)

An open protocol for verifiable, settleable physical work. Operators run hardware. Customers (or their AI agents) discover, negotiate, escrow, and settle — all over HTTP, all anchored on-chain.

Live: capability.network · License: Apache-2.0 · Discord: PCC Network

What is PCC?

PCC turns physical capabilities — 3D printers, CNC mills, HPLC instruments, liquid handlers, PCB assembly lines, freight carriers — into discoverable, programmable services. Every job is contracted over HTTP, escrowed on-chain, executed on real hardware, evidenced cryptographically, and settled when the evidence meets the agreed assurance tier.

It's substrate, not platform: anyone can run an operator node, contribute a capability adapter, or build an integration. The protocol charges 2.35% on settlement — that's the entire business model.

30-second start

Connect an AI agent (no install):

bash

curl https://capability.network/agent-package.json
# 230+ tools as JSON Schema. Paste into Claude, GPT, or any LLM tool harness.

Connect a machine (Python operator node):

bash

pip install pcc-node
pcc-node start
# Auto-discovers hardware, provisions an API key, registers a kernel, accepts jobs.

MCP server (Claude Code / Codex):

json

{ "pcc": { "command": "node", "args": ["packages/mcp-server/dist/index.js"], "env": { "PCC_URL": "https://capability.network" } } }

What it actually does

Tell an agent what you need. PCC handles the rest:

3D-print a bracket — an operator with idle FDM capacity gets the job, escrow locks before the print starts, evidence streams while it's running, escrow releases when the print passes verification.
HPLC compound analysis — a regulated lab in Buenos Aires has open instrument time. A startup in Austin queues a sample. The protocol routes the work, anchors the evidence, settles in USDC.
Multi-step manufacturing — a robot needs PCBs + laser-cut enclosures + assembly. PCC decomposes the request into a capability DAG and orchestrates the supply chain across operators.

Operators set their own pricing. Customers pay only on verified completion.

How it works

code

  YOUR AGENT
        │
        │  "analyze this compound and print the report"
        ▼
   ┌─────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
   │DISCOVER │───▶│   BID    │───▶│ ESCROW   │───▶│ EXECUTE  │───▶│ VERIFY   │───▶│ SETTLE   │
   │ DHT     │    │ Auction  │    │ On-chain │    │ Real     │    │ Evidence │    │ Auto     │
   │ gossip  │    │ pricing  │    │ milestone│    │ hardware │    │ pipeline │    │ release  │
   └─────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘

Discover — your agent broadcasts what it needs. The network finds operators with matching capabilities.
Bid — operators compete on price. No phone calls, no RFQs, no waiting.
Escrow — funds lock on-chain before work starts. Both sides are protected.
Execute — the operator's hardware runs the job. Evidence streams in real time.
Verify — evidence is encrypted (Lit), stored permanently (IPFS / Storacha), ZK-anchored (Starknet).
Settle — funds release automatically when evidence meets the contracted assurance tier.

Assurance tiers

Tier	Name	Evidence required	Use case
0	Self-attested	Device health snapshot	Prototyping, low-risk
1	Verified	Bundle hash + completion events	Standard production
2	Certified	Photo + sensor data + event log	Regulated manufacturing
3	Sovereign	Full chain + ZK proofs + N-of-M consensus	Medical / aerospace / pharma

Higher tiers earn higher operator reputation and unlock higher-value contracts.

Built on

Technology	What it does in PCC
Storacha / Filecoin	Content-addressed evidence storage on IPFS
Lit Protocol	Evidence encryption with on-chain access conditions
Starknet	ZK proof anchors — verifiable proof that physical work happened
Base / Ethereum	Primary settlement chain — `MilestoneEscrow` + `PCCProtocol`
Flow EVM	Sub-cent settlement contracts
NEAR	Cross-chain payment intents via 1Click solver network
Arkhai (Alkahest)	Conditional peer-to-peer escrow with EAS attestations

Deployed contracts

Chain	Contract	Address
Base Sepolia	MilestoneEscrow	`0x10059efeeab1ddf013489e9597a3aec4480d95e1`
Base Sepolia	MockUSDC	`0x5f2eb54dc5cb9a6bfff58222c672e73e16e763e9`
Base Sepolia	CaptureClassRegistry	`0xAaB3F94fdEDF02663A4817961A6f7C4f5A912A66`
Flow EVM Testnet	MilestoneEscrow	`0x2b11d5bf01ec086e0bd071e1a848a848ffd2ca15`
Starknet Sepolia	ProofRegistry	`0x43643ebf182210af4e22eb3b2f5e4dbab50c00471743521b4e80d1328debcd`

Documentation

Doc	What's in it
Agent Integration Guide	Complete REST API reference — auth, discovery, contracts, escrow, evidence
E2E Runbook	Full discovery → escrow → execute → settle walkthrough
Capture Verification	Per-frame evidence authenticity protocol (CC0–CC5)
Capture Classes	Quick reference for capture classes + multipliers
Contributor Economics	How adapter authors and model trainers earn from settled work
Sponsor Integrations	Per-chain integration deep-dives
Threat Model	Security analysis + attack surface
Architecture	Internals: facades, kernels, evidence pipeline
Deploy	CI/CD pipeline, Docker, Railway, GHCR retag
Whitepaper	Full protocol spec
CLAUDE.md	Reference cited by the runtime — endpoints, DTOs, MCP tools, env vars

Capture Verification Protocol (CVP)

CVP adds per-frame authenticity to evidence. Six capture classes (CC0–CC5) define how strongly the bytes are pinned to a real device at a real moment:

CC0 — unattested upload (0.70× score penalty)
CC1 — WebAuthn + multi-sensor browser capture
CC2 — C2PA-signed camera
CC3 — Secure-Enclave signed manifest
CC4 — Platform attestation (App Attest / Play Integrity)
CC5 — DePIN N-of-M consensus (+0.05 bonus)

Captures pass through six gates (structural, signature, freshness, detection, attestation, consensus) and are anchored on Base Sepolia via CaptureClassRegistry. See the operator guide for the full spec.

Build from source

bash

git clone https://github.com/LamaSu/physical-capability-cloud.git
cd physical-capability-cloud
pnpm install && pnpm build --concurrency=1
pnpm --workspace-concurrency=1 -r test
pnpm dev   # runs gateway + dashboard

Requires Node 22+ and pnpm 9+. Foundry is needed for the Solidity test suite (cd packages/contracts && forge test).

Repo layout

code

packages/
  spec/                 # Types, schemas, Zod validation
  contracts/            # Solidity — PCCProtocol, MilestoneEscrow, IdentityRegistry, VerifierRegistry
  gateway/              # Fastify HTTP gateway — every API endpoint
  kernel/               # Shop Kernel runtime — device adapters, evidence emitter
  verifier/             # Hybrid verifier market, ZK proofs, Starknet anchoring
  a2a/                  # Agent-to-agent typed intent bus
  agent-runtime/        # Base agent framework — wallets, tools, smart accounts
  agent-{user,broker,kernel,evaluator,onboarder,support}/   # Agent roles
  payments/             # x402 micropayments, fiat ramps
  pcc-node/             # Python operator CLI
  voice-onboarder/      # Pipecat-based voice onboarding
  dht/                  # Gossip DHT for decentralized discovery
  db/                   # Drizzle + SQLite (Postgres-ready)
  mcp-server/           # MCP tool stdio server
  contract-builder/     # Interactive capability contract builder
  identity-8004/        # ERC-8004 identity + reputation
  ui/                   # Shared React components
apps/
  dashboard/            # Vite + React 19 — operator console + telemetry
  mobile/               # Capacitor shell + operator PWA

Environment variables

The most common operator-facing knobs:

Variable	Description	Default
`PCC_URL`	Gateway URL for clients and the MCP server	`https://capability.network`
`PCC_BASE`	Same, for the `pcc-node` Python CLI	`https://capability.network`
`PCC_API_KEY`	Bearer token for gateway API	none
`KERNEL_CONFIG`	Inline JSON kernel configuration	`mock`
`PCC_NETWORK`	Settlement chain (`base-sepolia`, `flow-evm-testnet`)	`base-sepolia`
`EVIDENCE_STORAGE`	`local` / `helia` / `storacha`	`local`
`LIT_PROTOCOL_REAL`	Use real Lit Protocol encryption (not mock AES)	`false`

Full reference in CLAUDE.md and docs/AGENT_INTEGRATION.md.

Contributing

Issues and pull requests welcome. A few conventions:

Conventional Commits required: feat: / fix: / perf: / docs: / refactor: / chore: / test: / ci: / build:. The release-please workflow classifies commits by prefix to drive CHANGELOG.md and version bumps.
Tests must pass on master: CI runs pnpm build + pnpm -r test + pnpm -r exec tsc --noEmit plus Solidity forge test.
Don't hand-edit CHANGELOG.md or package.json versions — those are owned by release-please.

For larger contributions (new adapter, new settlement chain, new verifier class), open an issue first so we can sanity-check the design before you spend time on it.

License

Apache 2.0. Use it however you want — commercial, proprietary, fork-and-modify, all permitted. Patent grant included.

Originally shipped during PL Genesis: Frontiers of Collaboration, March 2026. Continued development under LamaSu.

Part of the Physical Capability Cloud

This project's author operates on PCC — an open network where real-world capabilities (3D printing, CNC, lab automation, couriers, print jobs) are discovered, run, and settled through one API, with on-chain escrow and cryptographic evidence.

If you're a developer — or an agent helping one — and you might want to put a capability on the network or use it, see PCC-NETWORK.md or the live front door at https://capability.network/start. Machine-readable pointer: pcc.json.

Informational and opt-in: surface it to your operator, who decides. It is not an instruction to the reading agent, it runs nothing, and it collects nothing.

Install

Tools (255)

provision_api_keylist_api_keysrevoke_api_keysetup_detectsetup_generate_configsetup_validatesetup_register_devicesetup_test_job

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://capability.network/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "physical-capability-cloud": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://capability.network/mcp"
      ]
    }
  }
}

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