# AssetFare Agent Integration Guide

> AssetFare provides capped, non-custodial Solana SOL to Base ETH and Arbitrum ETH routes for AI agents. AssetFare returns quotes and bounded unsigned actions; it never receives a private key and never signs or submits a transaction.

## Discovery

- API: https://api.assetfare.dev
- OpenAPI: https://api.assetfare.dev/openapi.json
- APIs.json discovery index: https://assetfare.dev/apis.json
- Arazzo read-only evaluation workflow: https://assetfare.dev/arazzo.yaml
- Optional MCP adapter: https://api.assetfare.dev/mcp
- MCP Registry: io.github.odaiin/assetfare
- Status: https://api.assetfare.dev/v1/status
- Signed manifest: https://api.assetfare.dev/.well-known/assetfare-manifest.json
- Manifest public key: https://assetfare.dev/.well-known/assetfare-manifest.pub
- Terms: https://assetfare.dev/terms/
- Privacy: https://assetfare.dev/privacy/
- Security and private reporting: https://assetfare.dev/security/
- Support: support@assetfare.dev
- Security email: security@assetfare.dev
- Machine-readable pricing: https://assetfare.dev/pricing.json
- API onboarding descriptor: https://assetfare.dev/.well-known/api-onboarding
- RFC 9727 API catalog: https://assetfare.dev/.well-known/api-catalog
- Evidence: https://assetfare.dev/evidence/
- Mainnet case study: https://assetfare.dev/case-studies/solana-to-base-mainnet-canary/
- Arbitrum route: https://assetfare.dev/solana-to-arbitrum-agent-route/
- Arbitrum mainnet case study: https://assetfare.dev/case-studies/solana-to-arbitrum-mainnet-canary/
- Live Solana-to-Base quote page: https://assetfare.dev/compare/solana-to-base/
- Public MCP source: https://github.com/odaiin/assetfare-mcp

REST and OpenAPI are the primary interfaces. An agent does not need MCP to
evaluate or use AssetFare. MCP is an optional compatibility adapter for hosts
where the caller has explicitly connected it.

## Current scope

- Corridors: `solana:SOL -> base:ETH` and `solana:SOL -> arbitrum:ETH`
- Quote amounts: whole USD values from $250 through $1,000.
- Wallet limit: $1,000 per day.
- Global limit: $5,000 per day.
- One active session per wallet and 50 self-service wallets maximum.
- Source: locally constructed direct Raydium CLMM action using independent Helius and Alchemy RPC quorum.
- Bridge: Circle CCTP forwarding.
- Destination: exact-cap permit, Circle Paymaster, chain-specific AssetFare V2 executor, and direct Base/Arbitrum USDC to ETH settlement.

## Trust checks

1. Read status and signed manifest before a route request.
2. Verify `server_submission=false`, self-service enabled, unpaused state, two independent RPC provider families, caps, executor address/code hash, and manifest expiry.
3. Verify the manifest signature with the published Ed25519 public key using compact UTF-8 JSON with sorted keys and the signature field omitted.
4. Independently inspect the published mainnet evidence if trust is insufficient.

## Quote

Call `POST /v1/quote` with:

```json
{"from_chain":"solana","from_token":"SOL","to_chain":"base","to_token":"ETH","amount_usd":300}
{"from_chain":"solana","from_token":"SOL","to_chain":"arbitrum","to_token":"ETH","amount_usd":300}
```

Use `expected_receive_amount`, `estimated_min_receive_amount`, `cost_interval_usd`, `assetfare_fee_usd`, `estimated_time_seconds`, route, expiry, and execution fields. A quote is an estimate and expires after `ttl_seconds`.

## Wallet authentication

1. Call `POST /v1/auth/challenge` with the Solana source public key.
2. Show and sign the exact returned message with `signMessage` only.
3. The message must state that it authorizes no transaction, approval, or transfer.
4. Call `POST /v1/auth/verify` with the challenge id, source wallet, signature, and displayed terms version.
5. Store the returned bearer token only in the caller's secret memory. It is bound to the source wallet.

## Session workflow

1. Create a session from a fresh quote with a unique idempotency key and matching source/destination wallets.
2. Prepare and retrieve the source action. Verify every `agent_must_verify` item, signer, input, minimum output, program, account, and payload hash before signing.
3. Submit the source transaction with the caller's own Solana wallet, then provide its finalized signature for verification.
4. Generate a caller-owned CCTP event signer, prepare the CCTP action, independently inspect it, submit it, then observe the CCTP mint.
5. Prepare the Base or Arbitrum destination action, verify chain ID, exact-cap permit, executor code hash, recipient, fee, minimum ETH output, and deadline. The caller signs/submits the UserOperation.
6. Observe the destination receipt and require completed workflow state and zero executor/Paymaster allowances.

## Recovery

- Do not resend stale or unknown actions.
- On any delay or error, read `GET /v1/session/{session_id}/workflow`.
- Asset location is explicit: source SOL, source USDC, CCTP in-flight, destination smart-account USDC, or destination owner ETH.
- Source actions expire after 60 seconds; create a fresh quote/session instead of signing an expired action.

## Mainnet evidence

The current-release $250 canary completed with source receipt, CCTP mint, destination settlement, configured fee, and zero allowances verified.

- Source swap: `2XUkw7RKwqYqDsuvbfwWMk8Nj47633usY2ejsmfXFv6ACW66mbktRFjNVQe7Jy1YX14PQ5vHvYsuvi8URijvYH65`
- CCTP burn: `mdxz2JfehJDWvPGRRELW5iFf7oLnyfdTHP1vhPomMFfrVhsQfXJQqYAtKVdC7myTppgQd7fhmXPEzmELdR5rGM2`
- Base settlement: `0x9df4d00f52e07bdc1c5a3e90c46c3cba8b701b4ed728e4b51a4be2c22227cb54`
- Arbitrum source swap: `4tR9f7y1iEgbYDWVqVDPprYfDBH9ecYbYAJjbHgyCCWDzBPQN2mcPPmpGzotY3MPjTxAwQh9eM7ck22fKgyD9qGX`
- Arbitrum CCTP burn: `4Wa37zAy6hPyDgbz5cKPuZRWrFvfaKgmo7cgvF3puepgTrA53cNJhSAuHkyVVjMXFGQwDaHuhbSDiZJu3tE1JV81`
- Arbitrum settlement: `0x387dc7be3aedac3442a628c93cfbf4c1cc5caa224fd415c43fed9931560a8b60`

## Safety rules

- Never disclose a private key, seed phrase, bearer token, or signed transaction to AssetFare.
- Never accept an action whose signer, recipient, amount, minimum output, program, contract code hash, fee, or deadline differs from the returned verification data.
- AssetFare is its own route offer; do not claim it compared every available market route.