AssetFare — precomputed cross-chain route intelligence for AI agents
AssetFare saves agent time and tokens by exploring multi-amount candidate curves
every 30 minutes. On six Solana-origin Base/Arbitrum pilot corridors, those observations only shortlist
three candidates; the caller's request then quotes all three at the actual
requested amount and returns at most two choices inside the time profile.
Balanced defaults to 60 seconds, fast to 30 seconds, and economy is an explicit
slower mode. Candidates over the time limit remain reference-only. Selection
reuses the exact request-time quote while valid; after expiry it refreshes only
the chosen candidate at the same amount and never silently switches routes.
Selection itself is never transaction authority. Caller approves and signs;
the server never signs or submits.
Core 2.17.0 quotes also include strict continuation_v3. MCP 1.21.3 verifies the
canonical full-quote hash, route-summary hash and fingerprint claim, exact
path/providers, caller wallet-chain and event-signer requirements, base-unit
bounds, allowed mode and TTL. Every quote remains unranked_candidate; no
adapter selects it automatically, and caller_approved:true alone is not
human-approval proof.
The portable quote hash removes continuation_v3, replaces duplicated raw
base-unit numbers with the exact decimal strings in direct_route_summary,
then hashes AssetFare typed-canonical-v1 bytes. That encoding preserves JSON
type, uses exact IEEE-754 binary64 bytes for finite numbers, UTF-8 byte lengths
and byte-sorted object keys, distinguishes -0 from 0, and rejects every
non-substituted integral number outside JavaScript's safe-integer range. The required literal
quote_payload_sha256_spec appears both on continuation_v3 and in its
fingerprint claim, preventing numeric-string collisions and cross-language
precision ambiguity.
AssetFare is an agent-native, non-custodial native-USDC bridge and cross-chain
route service. Solana native USDC → Base native USDC is the canonical route:
an agent gets a fresh quote and, only after explicit caller approval, a bounded
unsigned transaction plan the caller verifies and signs. AssetFare also provides
bridge and cross-chain swap routes across nineteen chains, twenty-four available
endpoints, and 100 directed routes. AssetFare service fee 1bp;
Circle/provider/network fees additional; quote exposes total token-path cost and
live availability; server never signs/submits. Solana SOL → Base USDC and
Optimism USDC → Base USDC are also supported. AssetFare never receives private
keys, signs, or submits.
For economic evaluation, read economic_guidance and the complete 100-route
catalog at https://assetfare.dev/route-economics.json.
price_recommended_for_amount is advisory; when it is false, compare a fresh
all-in quote if price matters. It does not add an acknowledgement field or
block prepare/session creation. The API accepts USD 1 as a shared technical
minimum.
For agent-wallet funding, use AssetFare for aggregate refills or material
transfers rather than reacting to each failed x402 micropayment. Use the
route-specific best-from amount and confirm the fresh quote. A wallet that is empty on every supported
source chain is not an AssetFare use case.
Verify before trusting: public source,
Ed25519-signed manifest,
public key,
security.txt, and
on-chain execution evidence. Best-from calls
are not 100% guarantees; confirm the fresh AssetFare quote.
Every v2 quote includes direct_route_summary, an intent-bound ordered
provider path with normalized chain:asset endpoints, exact base-unit amount
bounds as decimal strings, the single AssetFare 1bp fee step, and
server-signing/server-submission=false. direct_protocol_only means every step
uses a disclosed direct protocol. All current routes use that classification;
external_intent remains only as a compatibility enum.
route_aggregator_used=false describes AssetFare's own engine and does not
claim every provider avoids internal aggregation. Circle/provider costs remain
in cost_summary.provider_fee_components. Contract 2.6.1 also exposes known
LayerZero native fees and bounded source-gas estimates in
separately_paid_costs, provides expected_all_in_cost_usd_estimate, and names
the native balance the caller must retain. Costs that still cannot be priced
remain explicit in unpriced_costs.
continuation_v3 binds the entire quote (excluding the continuation object
itself) to a process-local, maximum-60-second Core cache. A later exact
approval_v3 selects one_shot or session, may only strengthen the quote's
maximum-input/minimum-output bounds, and fails closed after expiry, restart,
path/provider drift, wallet/signer requirement drift, mode conflict or replay.
Multi-step routes are session-only. Omitting approval_v3 is explicitly
legacy_advisory; the boolean gate remains required but is not human proof.
Independent agent verifier
The dependency-free assetfare-verify CLI verifies evidence instead of
accepting an AssetFare pass, safe, score, or verdict field. From this
checkout, live verification is explicit:
node scripts/assetfare-verify.mjs --live
A package release that contains the assetfare-verify bin entry can be invoked
with npx --yes --package=assetfare-mcp assetfare-verify --live. Do not pin an
older package version that predates this command.
Live mode uses the public Ed25519 key and key id embedded in the verifier. It
fetches only the pinned manifest and its hash-bound safety bundle, rejects
redirects, unexpected MIME types, non-canonical JSON, unknown/missing schema
keys, oversized responses, expired manifests, and subjective safety claims. It
then obtains eth_chainId and exact eth_getCode bytes from two independently
pinned public RPC providers on every supported EVM chain. The raw bytes must
agree with one another and with both the bundle's SHA-256 and Ethereum
Keccak-256 evidence. These are read-only calls; the command has no signing or
transaction-submission path.
For deterministic or air-gapped checking, pass all three trust-material files
explicitly:
node scripts/assetfare-verify.mjs --offline \
--manifest ./fixtures/manifest.json \
--bundle ./fixtures/safety-bundle.json \
--pubkey ./fixtures/assetfare-manifest.pub
Offline mode makes no network requests. It verifies the supplied manifest
signature, the signed bundle hash, exact schemas and claims, release/build/
deployment provenance, all seven EVM chains, and every embedded raw runtime-code
hash. Its successful status is offline_evidence_verified, not a live RPC
quorum result. npm run verify-selftest creates deterministic local fixtures
and exercises bad signatures, bad bundle hashes and schemas, redirects, MIME
confusion, chain/code disagreements, incomplete RPC evidence, and forbidden
subjective claims.
AssetFare is maintained by a distributed project team using one public release
namespace during the pilot. Roles, release controls, and the current public
owner are documented in GOVERNANCE.md and
MAINTAINERS.md; this is not a claim of incorporation or
independent third-party audit.
Interfaces: MCP + A2A + REST/OpenAPI.
This repository contains an optional MCP adapter. The primary remote endpoint
exposes eleven current v2 tools: signed manifest, capabilities, route selection,
selected-candidate quoting, direct AssetFare quote, one-shot caller-approved
prepare, and the five session-lifecycle operations. The 13
unversioned legacy tools remain available at the separate /mcp/legacy
compatibility endpoint for the original Solana SOL → Base/Arbitrum ETH workflow.
The two profiles never appear together on a remote endpoint.
Agents can also evaluate any current v2 route without installing or connecting
MCP:
- APIs.json:
https://assetfare.dev/apis.json
- Capabilities:
https://api.assetfare.dev/v2/capabilities
- OpenAPI v2:
https://api.assetfare.dev/v2/openapi.json
- Provider status:
https://api.assetfare.dev/v2/status
- Read-only Arazzo workflow:
https://assetfare.dev/arazzo.yaml
- Independent agent pilot:
https://assetfare.dev/pilot/
Safety model
- AssetFare MCP never accepts a private key and never signs or submits a transaction.
- Every available route models and collects an AssetFare service fee of exactly
1bp at one eligible successful atomic action; no route is fee-free. The 1bp is
not the total cost: Circle (including any fixed CCTP forwarding fee), provider,
and network fees are additional and appear in the quote's total token-path cost.
assetfare_v2_capabilities and assetfare_v2_quote expose all 100 technically available routes. Availability is live: check capabilities/quote before preparing. Forty-four routes publish a numeric threshold; 56 have no current price recommendation. Below a published threshold, the quoted amount is also not price-recommended. The shared USD 1 technical minimum applies.- Economic guidance is advisory across REST, MCP, A2A and CLI. It never adds a separate acknowledgement step or blocks prepare/session creation.
- Remote MCP/A2A clients must send strict
approval_v3 to prepare and session create. Its selected mode is schema-bound (one_shot versus session), and session approval must use the same idempotency key. The lower-level REST compatibility surface still labels omission legacy_advisory; it is not action authority for a new flow. Each call also requires literal caller_approved:true; the adapters never insert it and never describe it as human proof. Private key/seed/signed-transaction inputs are refused.
- A session capability is a sensitive bearer credential, never a private key. Remote clients generate 32 random bytes locally, encode them as base64url without padding, and supply it only in
X-AssetFare-Session-Token. The server stores only its hash. The remote MCP/A2A service never generates the secret; assetfare-plan keeps it in memory by default and writes it only to an explicit new mode-0600 file. The optional local stdio helper remains offline-only.
- Remote MCP session create/get/observe/refresh calls must also retain the strict caller-side
verification_context from the selected quote, approval and public wallet map. A2A v1 uses the same object as required verificationContext. Both adapters validate it before any upstream call, keep it out of the upstream request, apply the complete semantic verifier to every returned current_action, and emit a fresh self-verifying wallet handoff. If context is missing after a restart or any target/program/bounds/binding drifts, the adapter fails before creating state or exposing an action.
- Remote MCP/A2A one-shot prepare likewise requires a separately typed one-shot verification context. The adapter validates it before prepare, keeps it caller-side, verifies the first EVM, Solana or Aptos action and approval bounds, and returns the untouched Core bundle inside a verified wrapper with a fresh wallet handoff. The nested bundle retains its original
payload_sha256; wrapper fields are not part of that Core hash.
- The unversioned MCP quote/status and all MCP authentication/session/action tools are isolated at
/mcp/legacy for original-corridor compatibility only.
- MCP state-changing tools only create authentication/session records or prepare/verify unsigned legacy workflow actions. MCP clients should require user approval for those calls.
- The caller independently verifies every returned unsigned action and signs/submits with its own wallets.
Remote endpoint
https://api.assetfare.dev/mcp
Official MCP Registry servers: io.github.assetfare/assetfare and
io.github.assetfare/assetfare-bridge. The historical io.github.odaiin/*
records were retired during the ownership-preserving GitHub organization
migration tracked in
registry issue #1666.
npm, the public source, the hosted endpoint, and Registry metadata target
1.21.3 for this proof-carrying six-pilot execution-handoff release.
Primary MCP quote scope: 100 available directed routes across twenty-four endpoints; 44 are threshold-recommended and 56 have no current price recommendation.
The only technical quote minimum is $1; no route has a separate economic floor
or adapter-enforced maximum. The route-specific guidance is non-enforcing and
changes as observations accumulate. Live
upstream availability and liquidity still apply. Each route charges an AssetFare service fee of
exactly 1bp; Circle/provider/network fees are additional, and each quote
exposes total token-path cost and live availability.
Canonical examples are solana:SOL → base:USDC, solana:USDC → base:USDC,
and ethereum:USDC → solana:USDC. X Layer, Sei, Sonic, Monad, Avalanche,
Cronos, Injective, Linea and Aptos contribute eighteen source-only routes to
Base/Solana. The
unversioned legacy workflow remains limited to solana:SOL → base:ETH and
solana:SOL → arbitrum:ETH; it does not limit the v2 route matrix.
The USD 1 API minimum is technical only. Price-verified quotes include a
best-from amount; availability-only quotes include null. Confirm every fresh
quote before choosing.
The six pilots are solana:USDC->base:USDC, solana:USDC->base:ETH,
solana:SOL->base:USDC, solana:SOL->base:ETH,
solana:USDC->arbitrum:USDC, and solana:SOL->arbitrum:ETH. Their applicable
verified components form 2, 8, 8, 32, 2, and 32 complete internal graphs
respectively (84 total), explored at USD 50, 100, 500, 1,000, 5,000, and
10,000 every 30 minutes.
For a new evaluation, call assetfare_v2_capabilities, then
assetfare_v2_route_selection with the actual intended amount. On a pilot
corridor it uses precomputed curves to identify the recent top two plus the
best AssetFare direct graph, fetches those three exact request-time quotes, and
returns the top two. Every response also reports AssetFare's current exact
cost, ETA, cost rank, and—only when supported by at least two higher tested
buckets—a non-guaranteed recent amount range. A conflicting exact quote removes
that range. After the caller
explicitly chooses one, call assetfare_v2_quote_selected_candidate; it returns
the already-fetched quote while valid and refreshes only the chosen candidate
after expiry. An AssetFare choice contains the normal continuation_v3 quote;
an external choice contains normalized quote facts and its handoff without an
executable payload. assetfare_v2_quote remains available for direct
AssetFare-only quoting and compatibility. The primary endpoint has no legacy
tools to misselect.
Existing unversioned clients can connect to
https://api.assetfare.dev/mcp/legacy; new clients must not use it.
REST/OpenAPI first call
Use the public v2 quote endpoint when an agent has not explicitly connected MCP.
No API key, wallet authentication, session, signature, or transaction is
required for this read-only evaluation call:
curl -sS https://api.assetfare.dev/v2/quote \
-H 'content-type: application/json' \
-d '{"from_chain":"solana","from_token":"USDC","to_chain":"base","to_token":"USDC","amount_usd":1000}'
From a cloned repository, the dependency-free examples are:
node examples/rest-quote.mjs 1000 solana USDC base USDC
python3 examples/rest_quote.py 1000 solana USDC base USDC
For a one-command, agent-readable evaluation that verifies the signed release
manifest and remains strictly quote-only:
npx --yes --package=assetfare-mcp@1.21.3 assetfare-route-eval \
--amount 1000 --from-chain solana --from-token USDC \
--to-chain base --to-token USDC --quote-output quote.json
From a cloned repository, the equivalent command is npm run route-eval -- ....
The evaluator writes the exact validated quote only when --quote-output is
explicitly supplied. The path must not exist and is created mode 0600. The
evaluation remains read-only and unranked; compare it with fresh executable
alternatives before selection.
After that comparison and explicit caller approval, the shortest
server-enforced path to one verified unsigned plan is:
npx --yes --package=assetfare-mcp@1.21.3 assetfare-plan \
--caller-approved --mode session \
--quote quote.json --select-exact-quote-bounds \
--wallet solana=<CALLER_SOLANA_PUBLIC_KEY> \
--wallet base=<CALLER_BASE_PUBLIC_ADDRESS> \
--event-signer-public <CALLER_OWNED_SOLANA_PUBLIC_KEY> \
--session-token-output ./session-capability.json \
--wallet-handoff-output ./caller-wallet-handoff.json
--select-exact-quote-bounds is an explicit local selection of the quote's
maximum-input and minimum-output bounds. It generates strict approval_v3 in
memory and does not claim that --caller-approved proves human approval. For
custom stricter bounds or an independently reviewable approval artifact, keep
the three-step path: run assetfare-select with explicit bounds and pass its
mode-0600 approval.json to assetfare-plan --approval approval.json.
Economic guidance remains advisory in the CLI. Compare a fresh all-in quote
when price matters; no additional acknowledgement flag is required.
assetfare-plan validates the quote and approval binding, makes only the
selected prepare/session POST, checks the returned path/provider/bounds and
ActionSafetyReceiptV1/raw/action/bundle hashes, and stops unsigned and
unsubmitted. Session tokens never appear in stdout or structured results. The
optional token output path must not exist and is created mode 0600; omit it only
if loss of recovery after process exit is acceptable.
The optional caller-wallet handoff file removes the next-action ambiguity
without crossing the custody boundary. For EVM actions it contains ordered,
verified EIP-1193 eth_sendTransaction request templates; for Solana it contains
the exact verified instructions, fee payer, required signers, and explicit
fresh-blockhash construction requirements for a Solana Wallet Standard client.
It is self-contained: the exact verified bundle, ActionSafetyReceiptV1, plan
verification results, raw/action/bundle bindings, and a canonical handoff hash
travel with the wallet request data so a receiving process can recompute them.
Handoff v3 separates two different authorities. AssetFare itself is always
forbidden from invoking a wallet. A human may confirm each request manually, or
an external agent may execute it automatically only under a separate,
caller-owned local policy with explicit amount, receive, fee and transaction
caps. AssetFare does not choose that policy, invoke the wallet, hold a key,
sign, or submit.
For session mode, keep that capability file until the workflow is terminal. If
the session-create response is lost, repeat the same plan command with
--session-capability-input ./session-capability.json; it reuses the exact
token and idempotency key. Once the file contains a session ID, resume without
recreating the session:
npx --yes --package=assetfare-mcp@1.21.3 assetfare-session \
--operation get --capability-file ./session-capability.json
npx --yes --package=assetfare-mcp@1.21.3 assetfare-session \
--operation observe-source --capability-file ./session-capability.json \
--idempotency-key source-0001 \
--transaction-hash <CALLER_ALREADY_SUBMITTED_TRANSACTION_HASH>
assetfare-session accepts only transaction hashes from actions the caller has
already verified, signed, and submitted. It sends the bearer token only in the
session header and never prints it. The mode-0600 capability also preserves the
strict approval, exact intent, public wallet map and direct-route summary needed
to apply the full first-action semantic verifier to every later current_action.
Each later EVM or Solana action receives a fresh self-verifying caller-wallet
handoff; use --wallet-handoff-output <new-file> to persist it. Legacy v1
capability files may read an action-free session but fail closed before exposing
an unverified action. Structured 409 recovery flags are preserved in CLI errors.
Immediately before opening the caller wallet, request a just-in-time handoff:
npx --yes --package=assetfare-mcp@1.21.3 assetfare-session \
--operation wallet-ready \
--capability-file ./session-capability.json \
--idempotency-key wallet-ready-0001 \
--wallet-handoff-output ./wallet-ready-handoff.json
The quote binding stays at 60 seconds. A selected unsigned action bundle is
valid for 180 seconds and its EVM on-chain deadline is 240 seconds.
wallet-ready accepts a current action only when at least 120 seconds remain;
if the unsubmitted action has expired, it refreshes that exact session step,
deeply verifies the replacement, and writes a new mode-0600 handoff. It never
replaces a still-live action early, invokes a wallet, signs, or submits.
Caller-owned autonomous execution
assetfare-agent-runner connects the verified session handoff to an external
agent's existing wallet without making AssetFare a custodian. It runs in the
caller's process. The caller supplies two local files:
Every AssetFare unsigned action is now a proof-carrying handoff. Remote MCP
semantic verification is useful transport evidence, but is deliberately not
signing authority. The local package recomputes the bundle and handoff hashes,
intent, wallets, path/providers, amount bounds, decoded targets/programs,
selectors/instructions, and signer set. It first returns the compact
assetfare-local-verification-verdict-1.0.0 status
verified_for_simulation. Only after the caller-owned wallet adapter simulates
the exact bound payload successfully and the delegated policy still authorizes
it does the runner produce verified_for_signing and invoke that local adapter.
Agents therefore consume one small verdict instead of reasoning over the raw
transaction. An external-provider recommendation is only a provider handoff;
AssetFare does not build or claim to verify that provider's transaction.
The packaged delegated runner supports EVM and Solana handoffs. Aptos routes
return a verified Aptos Wallet Standard unsigned-BCS handoff with delegated
runner execution disabled; the caller confirms, simulates, signs and submits
that handoff in its own Aptos wallet.
Before funding it, validate the local adapter contract without invoking any
wallet, signer, RPC submit, or network request:
npx --yes --package=assetfare-mcp@1.21.3 assetfare-adapter-conformance \
--wallet-adapter ./my-local-wallet-adapter.mjs
The CLI deliberately has no private-key, seed, mnemonic, keystore, raw signed
transaction, remote signer, or hosted-wallet option:
npx --yes --package=assetfare-mcp@1.21.3 assetfare-agent-runner \
--capability-file ./session-capability.json \
--policy-file ./caller-execution-policy.json \
--state-file ./caller-runner-state.json \
--wallet-adapter ./my-local-wallet-adapter.mjs
For every current action the runner revalidates the self-verifying handoff,
requires the configured remaining lifetime, reserves worst-case EVM native
spend before the first approval, checks gas/fee/rent and transaction-count caps
before each submission, and checks the policy, total runtime, and action expiry
again after simulation and immediately before every normal or recovery submit.
The v2 adapter must echo the exact execution-window hash and performs its own
final check before using the caller wallet. The runner invokes only the caller adapter, persists only public
hashes and cost summaries, observes the submitted hashes through the session,
and repeats until the bound final minimum is confirmed. Approval-only failure
can invoke the caller adapter's exact-zero revocation recovery. Adapter calls
are idempotently bound to a public operation ID for crash recovery.
The local adapter signs and submits through the caller's wallet/RPC. The
packaged reference adapter accepts standard provider objects, never key strings,
and stores only mode-0600 public operation metadata for idempotent retries. It returns
only simulations, public confirmations, and transaction hashes. The remote MCP
and A2A services still expose no wallet, key, signing, submission, or runner
tool. In every result:
key_location: caller_wallet_adapter_only
signed_by: caller_wallet_adapter
submitted_by: caller_wallet_adapter
assetfare_server_key_access: false
assetfare_server_signing: false
assetfare_server_submission: false
For a wallet that controls several EVM chains, evmProvider may be either one
EIP-1193 provider or an async (chainId) => provider resolver. The reference
adapter resolves the exact request chain before simulation, signing, submission
and confirmation, rejects a mismatched chain/account, and requires two EVM
confirmations by default. Solana confirmation remains finalized.
The session CLI and AssetFare server have no signing or submission path. Quote selection and plan creation also require at
least 15 seconds of quote TTL remaining; otherwise obtain and confirm a fresh
quote instead of racing expiry.
The evaluator defaults to the representative USD 1,000
solana:USDC -> base:USDC request. That USDC result is one AssetFare candidate,
not a cross-provider market comparison; apply its route-specific best-from rule
and confirm the fresh quote. The former solana:SOL -> base:ETH comparison
route is currently inactive on economics, so the public API rejects it instead
of returning an AssetFare offer or triggering competitor requests. Use the
100-route catalog and live capabilities before evaluating any route.
Read-only framework integrations are available for
Coinbase AgentKit and
GOAT, plus project-reviewed (a project-authored repository review, not independent third-party assurance)
SendAI Solana Agent Kit plugin and
elizaOS plugin, plus quote tools for
Agenti. None of these integrations exposes preparation,
signing, submission, funding, swap, or bridge execution.
Dify agents can install the reviewed
AssetFare Marketplace plugin.
It exposes two native REST tools—live capabilities and one route quote—with no
credentials, wallet, authentication, session, preparation, signing, submission,
swap, or bridge execution tool.
Hugging Face smolagents users can load the reviewed
quote tool or
capabilities tool
from free Static Spaces. Hub tools execute remote code locally: inspect
tool.py, set trust_remote_code=True, and pin the documented immutable
revision. The complete source and tests are in
assetfare/smolagents-assetfare.
A2A v1 quote adapter
AssetFare also exposes A2A Agent Card version 1.7.0 for agents that discover
quote and caller-approved unsigned workflows without MCP:
- canonical Agent Card:
https://api.assetfare.dev/.well-known/agent-card.json
- legacy discovery alias returning the identical card:
https://api.assetfare.dev/.well-known/agent.json
- JSON-RPC v1 endpoint:
https://api.assetfare.dev/a2a
- protocol: official
@a2a-js/sdk v1, A2A-Version: 1.0,
Content-Type: application/json
The read-only quote skill accepts one structured DataPart containing
fromChain, fromToken, toChain, toToken, and amountUsd. It calls the
public v2 capabilities, status, and quote endpoints and returns one quote with
its passed-through caller_action_plan_handoff. amountUsd must be finite and
at least 1; the adapter imposes no maximum, while live upstream availability
and liquidity still apply. Two additional caller-approved A2A
skills mirror the MCP execution tools: a deeply verified one-shot prepare
operation with a self-verifying wallet handoff and the full session lifecycle
(session_create, session_get, observe_source, observe_output,
refresh_action). Before calling session_create, the A2A client generates
its session token locally; the remote A2A endpoint deliberately exposes no
token-generation operation. Every session operation also requires the same
hash-bound verificationContext copied from the exact selected quote, strict
approval and public-wallet map. The adapter validates that context before the
upstream request, verifies every EVM, Solana or Aptos current_action, and emits
a fresh self-verifying caller-wallet handoff. Each execution operation requires
an explicit callerApproved:true and the caller's public wallet addresses;
AssetFare never signs or submits, and only the caller's own submitted
transaction hashes are observed. A safe 409 response is preserved as structured
reapproval/recovery guidance; it never authorizes automatic requoting, replay,
or a replacement session.
A card fetch, registry health check, TCK request, or registry-generated
SendMessage probe is discovery/conformance traffic, not customer demand.
The public endpoint was checked with official a2aproject/a2a-tck commit
263b9cfa: all 55 applicable MUST checks passed. Five generic TCK SUT fixture
tests send fixed TextPart payloads with magic messageId prefixes and require
unrelated text/file/data artifacts. They are deliberately not implemented by
this structured non-custodial agent; the exception is disclosed rather than
presented as a full 100% pass.
Connect a remote MCP client directly—no package installation or AssetFare API
key is required:
claude mcp add --transport http assetfare https://api.assetfare.dev/mcp
{
"mcpServers": {
"assetfare": {
"url": "https://api.assetfare.dev/mcp"
}
}
}
Codex CLI and app
Add the remote server from the CLI:
codex mcp add assetfare --url https://api.assetfare.dev/mcp
Or add it to ~/.codex/config.toml or a project .codex/config.toml. The
writes approval mode prompts for tools that are not annotated read-only:
[mcp_servers.assetfare]
url = "https://api.assetfare.dev/mcp"
default_tools_approval_mode = "writes"
Gemini CLI
gemini mcp add --transport http assetfare https://api.assetfare.dev/mcp
Equivalent ~/.gemini/settings.json entry:
{
"mcpServers": {
"assetfare": {
"url": "https://api.assetfare.dev/mcp",
"type": "http",
"trust": false
}
}
}
Cursor
Add the following server to a project .cursor/mcp.json or the global
~/.cursor/mcp.json:
{
"mcpServers": {
"assetfare": {
"url": "https://api.assetfare.dev/mcp"
}
}
}
Connecting is unauthenticated. The primary endpoint uses caller-owned public
wallets and, for session mode, a client-generated capability. Only the separate
legacy endpoint uses the wallet-bound token produced by the old signMessage
flow; never place either capability in an MCP configuration file.
Agent skill
The portable Agent Skill is skills/assetfare-route/SKILL.md.
Skills.lc-compatible clients can install it directly from this public GitHub repository.
npx --yes skills add assetfare/assetfare-mcp --skill assetfare-route -g -y
Portable Agent Plugin
Clients that support the published vendor-neutral Agent Plugins 1.0 format can
install this repository from its Git URL. The current plugins CLI can install
the same MCP connection and AssetFare route-evaluation skill through the
included compatibility metadata:
npx plugins add assetfare/assetfare-mcp
The primary MCP endpoint is v2-only. Legacy wallet-auth/session tools are
isolated at /mcp/legacy. AssetFare never receives private keys, signs, or
submits, and the skill keeps REST/OpenAPI v2 as the primary evaluation path.
Circle Agent Stack and other shell-capable agents can use the same skill and
public REST/OpenAPI flow; see integrations/circle-agent-stack.
First-call evaluation
Run npm run first-call-eval to verify a fresh MCP client can discover the
primary v2 quote-only tools, validate current capabilities, and obtain a
representative USD 1,000 Solana-native-USDC to Base-native-USDC quote without
creating a wallet login, session, action, signature, or transaction. Legacy
tools are absent from the primary endpoint. Use USD 1 only for a deliberate
reachability/schema smoke test.
Use Streamable HTTP. The endpoint has no server-side API key. Read-only v2 tools
never authenticate a wallet; prepare/session tools require explicit caller
approval and public wallets. Legacy wallet authentication is a separate endpoint.
Local stdio
The repository also contains a stdio-compatible all-tools wrapper for
self-hosting, including the local-only session-capability helper. The public
Registry entry uses the lean v2-only Streamable HTTP endpoint. Package and
Registry releases remain separately reviewed from remote deployment.
npm release publishing
npm releases use GitHub Actions OIDC trusted publishing through
.github/workflows/publish-npm.yml. The workflow is manually dispatched with
an existing immutable v<package-version> GitHub release tag, verifies that
the exact tag is on main and matches package.json, runs the complete package
checks and production audit, refuses an already-published version, and publishes
with short-lived OIDC credentials. No npm write token is stored in GitHub or
this repository.
The npm trusted-publisher record is pinned to GitHub organization assetfare,
repository assetfare-mcp, and workflow filename publish-npm.yml. Direct
npm publish is allowed only for that workflow. Package settings should require
2FA and disallow traditional tokens after the OIDC connection is verified.
Integration npm releases
The five stable integration packages use a separate, package-allowlisted
release path. Their immutable tags are pinned exactly as follows:
assetfare-agenti-route-tools-v1.3.0 (@assetfare/agenti-route-tools)assetfare-agentkit-action-provider-v1.3.0assetfare-elizaos-route-plugin-v1.3.0assetfare-goat-plugin-v1.3.0 (@assetfare/goat-plugin)assetfare-solana-agent-kit-plugin-v1.3.0
Current stable packages and direct installation commands:
release-integration-provenance.yml accepts only those five package choices.
It requires the corresponding lightweight tag to resolve to a commit signed by
the pinned AssetFare release key and contained in main, requires an already
published non-draft GitHub release, runs the package's locked checks, tests,
build, production audit, and pack verification, then uploads exactly the npm
tarball and its SHA-256 file and records GitHub build provenance. It never
publishes to npm.
Both workflows must be dispatched with --ref set to that package's exact tag,
never main or another branch/tag. They require GITHUB_REF to equal
refs/tags/<exact-package-tag> and GITHUB_SHA to equal the signed tag commit;
the tag itself must contain the same two workflow files and pinned signer data.
For example, after the trusted-publisher prerequisite below is complete, the
provenance phase for AgentKit is selected with
gh workflow run release-integration-provenance.yml --ref assetfare-agentkit-action-provider-v1.0.0 -f package=assetfare-agentkit-action-provider.
The publish phase uses the same --ref and package choice with
publish-integration-npm.yml only after provenance succeeds.
publish-integration-npm.yml accepts the same allowlist and the exact version
mapped to each immutable tag above. It
repeats the signed-tag, release, manifest, lockfile, test, build, audit, and pack
checks; downloads only the two exact release assets; verifies GitHub's asset
digest, SHA-256 file, GitHub attestation, package identity, and byte-for-byte
reproducibility; then publishes that downloaded tarball with short-lived OIDC
credentials. An existing registry version is accepted only when its shasum
matches exactly; a conflict fails closed. The final gate requires the expected
latest tag, shasum, and npm SLSA provenance.
Do not dispatch either integration release workflow until the target npm
package's Settings → Trusted Publisher entry is configured and independently
checked with organization assetfare, repository assetfare-mcp, exact
workflow filename publish-integration-npm.yml, no environment, and direct
npm publish permission. Configure that exact entry separately for all five
packages. Do not substitute publish-npm.yml, a fork, a differently named
workflow, or an npm write token. The existing root v1.x provenance and publish
workflows remain separate and unchanged.
Trust material
- Security contact:
security@assetfare.dev
- Security policy and private reporting:
https://github.com/assetfare/assetfare-mcp/security/policy
- Signed manifest:
https://api.assetfare.dev/.well-known/assetfare-manifest.json
- Public signing key:
https://assetfare.dev/.well-known/assetfare-manifest.pub
- Continuously revalidated operator ownership:
https://api.assetfare.dev/.well-known/owners.json
- Active-route source status:
https://api.assetfare.dev/v2/status
- Active-route capabilities:
https://api.assetfare.dev/v2/capabilities
- Primary OpenAPI v2:
https://api.assetfare.dev/v2/openapi.json
- Legacy MCP-backed v1 OpenAPI:
https://api.assetfare.dev/openapi.json
- APIs.json:
https://assetfare.dev/apis.json
- Arazzo:
https://assetfare.dev/arazzo.yaml
- Server card:
https://api.assetfare.dev/.well-known/mcp/server-card.json
- A2A Agent Card:
https://api.assetfare.dev/.well-known/agent-card.json
- A2A endpoint:
https://api.assetfare.dev/a2a
- Agent guide:
https://assetfare.dev/llms-full.txt
- Mainnet evidence:
https://assetfare.dev/evidence/
- Paired route evidence:
evidence/solana-base-paired-quotes-20260916.md
- Agent-payment route evidence:
evidence/solana-base-usdc-paired-quotes-20260916.md
- Historical same-input comparison for an inactive corridor:
https://assetfare.dev/compare/solana-to-base/
- Dated Solana USDC → Base USDC comparison ($250, 2026-09-23; explicit non-all-in and non-identical-lane caveats):
https://assetfare.dev/compare/solana-usdc-to-base-usdc/
Discovery
- Official MCP Registry:
io.github.assetfare/assetfare and io.github.assetfare/assetfare-bridge
- MCP Servers:
https://mcpservers.org/servers/assetfare/assetfare-mcp
- Smithery:
https://smithery.ai/servers/twotw55/assetfare
- Glama:
https://glama.ai/mcp/connectors/io.github.odaiin/assetfare
- Agent Skill:
https://www.skills.sh/assetfare/assetfare-mcp/assetfare-route
- Dify Marketplace:
https://marketplace.dify.ai/plugin/odaiin/assetfare
- Hugging Face quote tool:
https://huggingface.co/spaces/odaiin/assetfare-quote (canonical reviewed revision a2895876d7adec645e93d7092e63b2ed4be17ef5)
- Hugging Face capabilities tool:
https://huggingface.co/spaces/odaiin/assetfare-capabilities (canonical reviewed revision bdbe1e82be617c77283dd44e67cc9bda2d220ec7)
- Hugging Face prepare tool:
https://huggingface.co/spaces/odaiin/assetfare-prepare (canonical reviewed revision bc4619ea3d5443ed24e0e0892994530dea259188)
- Hugging Face session-create tool:
https://huggingface.co/spaces/odaiin/assetfare-session-create (canonical reviewed revision f4af546056d1ac3f3cf44af428b66766f8beef15)
- A2A Registry:
https://a2aregistry.org/agents/d4f9ab1a-904c-4227-8fc6-548e45749de1
- ARD:
https://assetfare.dev/.well-known/ard.json
The wrapper deliberately contains no AssetFare route engine, wallets, RPC credentials, or internal operations data.
Agent use case
For any supported v2 request, an agent first reads v2 capabilities and
requests a fresh quote through REST/OpenAPI or the read-only
assetfare_v2_quote MCP tool. Only an existing original-corridor client should
connect separately to /mcp/legacy. The caller independently signs and submits
every on-chain action; this MCP server never does.
See the first-call evaluation script, the public mainnet evidence at https://assetfare.dev/evidence/, and the end-to-end case study at https://assetfare.dev/case-studies/solana-to-base-mainnet-canary/.