AssetFare README

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 ; wrapper fields are not part of that Core hash.

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.

• a mode-0600 policy matching caller-owned-execution-policy-v2, containing only public wallets and explicit execution caps; and
• a local wallet adapter. The packaged standard-wallet-adapter already implements the AssetFare contract for a standard EIP-1193 provider and a Solana Wallet Standard wallet; the caller only wires its existing provider clients as shown in examples/caller-wallet-adapter.mjs.

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.0
• assetfare-elizaos-route-plugin-v1.3.0
• assetfare-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/.