Tachyon API

Tachyon is the agent-native Solidity/EVM smart contract engine. Rather than a human-first terminal flow, it exposes its compile/test/simulate/deploy workflow as MCP tools callable by Matrix agents. Tachyon runs as a stdio MCP server (tools/tachyon/tachyon.mjs).

MCP tools

Tachyon exposes nine tools:

Tool	Read/Write	Purpose
`tachyon_compile`	Read	Compile Solidity with forge; return ABI + bytecode + project_id
`tachyon_test`	Read	Run a Forge test suite; return structured per-case results (pass/fail/gas)
`tachyon_simulate`	Read	Dry-run an `eth_call` against a chain without broadcasting
`tachyon_deploy`	Write	Deploy a compiled contract on-chain (signs + broadcasts via embedded wallet)
`tachyon_call`	Read or Write	Invoke a contract method; `simulate_only=true` for reads, `false` for writes
`tachyon_chain_list`	Read	List configured chain RPC profiles (id, name, chain_id, explorer)
`tachyon_chain_register`	Write	Register or update a custom chain RPC profile
`tachyon_artifact_get`	Read	Fetch a cached compile artifact by contract name and project_id
`tachyon_registry_lookup`	Read	Resolve a prior deployment by idempotency_key + chain_id

Compile

POST /v1/compile (HTTP) or tachyon_compile (MCP)

sourcesobjectrequired

Map of workdir-relative path to Solidity source. Contracts under src/, tests under test/. OpenZeppelin and forge-std resolve automatically against the shared engine's baked corpus.

targetsarray

Optional contract names to return artifacts for; empty returns all.

project_idstring

Override the derived project ID (normally a deterministic sources hash).

optimizeboolean

Enable the solc optimizer.

via_irboolean

Compile through the Yul IR pipeline.

Returns artifacts (ABI + bytecode per contract), a stable project_id, and any compiler diagnostics.

curl -X POST https://tachyon.example/v1/compile \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "sources": {
      "src/Counter.sol": "// SPDX-License-Identifier: MIT\npragma solidity ^0.8.0;\ncontract Counter { uint256 public n; function inc() external { n++; } }"
    }
  }'

Test

tachyon_test (MCP)

sourcesobjectrequired

Map of workdir-relative path to content. Tests under test/, contracts under src/.

match_pathstring

forge --match-path glob (e.g. test/Token.t.sol).

match_contractstring

forge --match-contract filter.

filterstring

forge --match-test test-name filter.

Returns structured per-case results with pass/fail status and gas usage.

Simulate

tachyon_simulate (MCP)

chain_idstringrequired

Chain profile ID or numeric EVM chain ID. Paxeer is "paxeer-mainnet" or "125".

tostringrequired

Target contract address (0x...).

datastring

Pre-encoded calldata hex (0x...).

fromstring

Caller address (0x...).

valuestring

Wei value as decimal or 0x-hex.

blockstring

Block tag/number (default latest).

Dry-run only. Returns the raw return data and revert reason if it reverts.

Deploy

tachyon_deploy (MCP)

idempotency_keystringrequired

Caller-chosen key; repeat to dedupe a redeploy. A prior deploy with the same key + chain returns the existing address.

chain_idstringrequired

Target chain profile ID or numeric EVM chain ID.

contractstringrequired

Contract name to deploy (must exist in the registry for the project_id).

project_idstring

Project ID from tachyon_compile.

constructor_argsarray

Constructor arguments, in ABI order.

spend_cap_weistring

Optional per-tx spend cap (wei).

Signs and broadcasts via the caller's embedded wallet. The daemon's agent identity is forwarded automatically; custody policy is enforced wallet-side.

Call

tachyon_call (MCP)

tostringrequired

Target contract address (0x...).

methodstring

Function name to ABI-encode (with args). Omit to use pre-encoded data.

argsarray

Arguments for method, in ABI order.

abiobject

Inline ABI JSON to encode against (else resolved from contract + project_id).

contractstring

Contract name to resolve the ABI from the registry.

project_idstring

Project ID owning the artifact for ABI resolution.

datastring

Pre-encoded calldata hex when method is omitted.

simulate_onlyboolean

true = eth_call read (no broadcast, no wallet); false = broadcast.

chain_idstring

Target chain profile ID or numeric EVM chain ID.

spend_cap_weistring

Optional per-tx spend cap (wei) for the broadcast.

Chain management

tachyon_chain_list returns all configured chain RPC profiles (id, name, chain_id, explorer) and which is active.

tachyon_chain_register registers or updates a custom chain profile:

idstringrequired

Short profile ID (e.g. "my-chain"). Paxeer chain 125 is preconfigured as "paxeer-mainnet".

namestringrequired

Human-readable name.

rpc_urlstringrequired

JSON-RPC URL.

chain_idnumberrequired

EVM chain ID (uint).

explorerstring

Block explorer base URL.

Artifact registry

tachyon_artifact_get fetches a cached compile artifact (ABI + bytecode) by contract name and project_id.

tachyon_registry_lookup resolves a prior deployment by idempotency_key + chain_id (returns address, tx hash, confirmation state, or found=false).

MCP surface

How Tachyon is exposed to agents as MCP tools.