Advan: Solana trading tools

Advan

Advan is an open-source MCP server and HTTP API that gives AI agents Solana trading tools. Quotes and unsigned swap transactions come from Jupiter Swap API V2. Token risk and wallet portfolio reads are paid with x402 (exact scheme, USDC).

The server is non-custodial. It never signs a transaction and it never loads a trading key. build_swap_tx returns an unsigned base64 transaction for the user's own wallet (taker) to sign. SOLANA_KEYPAIR_PATH is read only by scripts/e2e-devnet-x402.ts.

Package name: advan-mcp (unregistered on npm when this tree was created on 2026-10-25). Change the "name" field in package.json before publishing. The advan-mcp bin name can stay.

Fees

Fees (hosted endpoint): Swaps built through Advan include a 1.00% (100 bps) platform fee via Jupiter's referral program. Jupiter keeps 20% of that fee, so Advan nets 0.80%. The fee shows in every quote (platformFee) before you sign. token_risk and wallet_portfolio cost $0.02 USDC per call via x402 (Solana mainnet). Quotes are free. Non-custodial: you sign every transaction in your own wallet; Advan never holds keys or funds. Self-hosted copies charge nothing unless the operator sets their own fee.

Hosted endpoint

• https://advan.fly.dev
• Streamable HTTP MCP: https://advan.fly.dev/mcp

PUBLIC_BASE_URL is that origin. x402 resource URLs and Bazaar metadata use it, because Fly terminates TLS and the app would otherwise advertise http://.

Deploy steps are in docs/DEPLOY-FLY.md.

What you can call

Jupiter base URL is https://api.jup.ag (Swap API V2). lite-api.jup.ag is not used. An optional JUPITER_API_KEY is sent as x-api-key. Keyless access is about 0.5 requests per second; Jupiter returns HTTP 429 past that, and Advan retries those responses with backoff (up to three waits). Set JUPITER_API_KEY for production. A portal key is the limit you should run with once more than one agent is calling.

Fees you should expect

Jupiter referral. When JUPITER_REFERRAL_ACCOUNT is set, every order sends referralAccount and referralFee. The allowed range is 50–255 bps (default 50). Jupiter keeps 20% of that fee, so 50 bps charged to the user nets 40 bps to the referral partner, and it replaces Jupiter's usual 2–10 bps platform fee. Quotes will look more expensive than calling Jupiter with no referral.

Jupiter picks the fee mint (SOL, then stables, then LSTs, then other tokens). If the referral token account for that mint does not exist, the swap still succeeds and your fee is dropped. Advan checks every order response:

• referralAccount matches the configured account
• feeBps equals the configured fee when gasless is false
• feeBps is at least the configured fee when gasless is true (gasless cost can add bps)
• feeMint has a configured referral token account, and that account is the V2 associated token account of the referral account for the mint (allowOwnerOffCurve, under the mint's token program, Token or Token-2022). That is what initializeReferralTokenAccountV2 creates. A swapped account fails the check. A legacy referral_ata PDA is accepted only when that account already exists on-chain.
• At startup Advan checks that each configured referral token account exists on SOLANA_RPC_URL. A missing V2 account is recorded. A wrong account, or a legacy PDA that does not exist, refuses to boot.

FEE_CHECK_MODE=fail (default) withholds the quote and the transaction when the fee itself is wrong. warn returns them with feeCheck.ok: false and logs a fee_check_failure event either way.

A token-to-token route can pick a feeMint you have not created an account for. REFERRAL_MISSING_MINT_MODE=requote (default) quotes that pair again without referralAccount / referralFee, returns the quote, and writes a referral_requote log line. fail refuses the swap. warn returns the original order with feeCheck.ok: false. Add the mint with REFERRAL_MINTS on npm run setup:referral if you want the fee on that pair.

Leave the account unset and orders are sent with no referral (a startup warning says so). JUPITER_REFERRAL_REQUIRED=true refuses to boot without the account and wSOL, USDC, and USDT token accounts.

x402. token_risk and wallet_portfolio use the exact scheme. The buyer pays USDC to X402_PAY_TO on X402_NETWORK. Default network is Solana devnet (solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1) and devnet USDC 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU. Mainnet is solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp and USDC EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v. The recipient USDC token account must already exist (npm run setup:payto-ata).

@x402/evm is a dependency because @coinbase/cdp-sdk/x402 loads it. Advan registers only the Solana exact scheme.

Coinbase CDP is the primary facilitator when CDP_API_KEY_ID and CDP_API_KEY_SECRET are set. PayAI (https://facilitator.payai.network) is used when the CDP /supported probe fails, and it is the only facilitator when CDP keys are absent. Verify and settle are sent to the facilitator whose advertised extra.feePayer is on the payment requirements. An in-flight payment is not handed to the other facilitator: that fee payer would not match, and the settlement would fail. When CDP fails in a way that is safe to fail over, Advan marks it down and the next payment challenge is rebuilt with PayAI's fee payer. The next probe is scheduled for X402_CDP_RECOVERY_INTERVAL_MS after the failure (default 5 minutes), not on a timer that started at boot. A healthy /supported restores CDP as primary, reloads payment requirements, and writes a facilitator_recovered log line. If that reload fails or times out, Advan goes back to PayAI and reloads those requirements instead of leaving them empty. Every fee payer a facilitator has advertised is kept, so a rotated CDP fee payer still settles with CDP. GET /health reports cdp as primary, down, or unconfigured, and cdpNextProbeAt while it is down. A settle timeout or HTTP 5xx is not treated as a failover. Failed verifications are logged as x402_verification with the facilitator's reason. The 402 body and PAYMENT-REQUIRED error shown to the client say payment could not be verified.

MCP payment requirements, including the Solana blockhash, are built on every paid call. HTTP builds them per request. Both use X402_RPC_URL, which defaults from X402_NETWORK and is never SOLANA_RPC_URL.

CDP's published fee after the free tier is $0.001 per successful settlement. PayAI Solana mainnet exact is $0.00133. Devnet PayAI settlements are free. At startup Advan warns, or exits when X402_PRICE_GUARD=refuse, if the price is below X402_MIN_FEE_MULTIPLE (default 5) times the applicable fee. $0.01 is about 7.5× the PayAI mainnet fee. $0.005 is not.

get_quote and build_swap_tx are not gated.

Guards

Before a quote or transaction is returned:

• requested slippageBps must be ≤ MAX_SLIPPAGE_BPS (default 300)
• if the client omits slippage, Jupiter's RTSE value in the response must still be ≤ the max
• amount must be ≤ MAX_INPUT_AMOUNT when that cap is set (base units). Unset prints a startup warning.
• USD size (amount × Jupiter Price V3) must be ≤ MAX_TRADE_USD (default 1000). Set MAX_TRADE_USD=off to disable it. A missing price refuses the trade while the cap is on. Startup warns loudly if both caps are off.
• absolute price impact must be ≤ MAX_PRICE_IMPACT_PCT (default 5). Jupiter's priceImpactPct is treated as a fraction

Swap signing

build_swap_tx defaults to the managed path (SWAP_SELF_BROADCAST_DEFAULT=false):

• JupiterZ (RFQ) routes are allowed. They need the market maker's co-signature, which Jupiter adds during POST https://api.jup.ag/swap/v2/execute with { signedTransaction, requestId }.
• The response includes submit.method: "jupiter", requestId, and coSignRequired when the router is jupiterz.
• The transaction field is unsigned. Sign it with the taker wallet, then send it to /execute promptly (lastValidBlockHeight or expireAt).

Pass selfBroadcast: true (or set the env default) to send excludeRouters=jupiterz. The tool then rejects a signatureFeePayer other than the taker, and rejects a response that is still a JupiterZ route. The taker signs and broadcasts that transaction on their own RPC.

Install

Node.js 20 or newer.

npm install

npm run build cp .env.example .env

Stdio (Claude Desktop, Cursor, or npx after publish):

npm start

or, once published:

npx advan-mcp

HTTP (plain JSON and Streamable HTTP MCP on /mcp):

npm run start:http

listens on $HOST:$PORT, default 127.0.0.1:8787

Docker sets HOST=0.0.0.0. Set ADVAN_ALLOWED_HOSTS when you bind a public interface.

Docker:

docker build -t advan .

docker run --env-file .env -p 8787:8787 advan

The image default for USAGE_LOG_PATH is /data/usage.jsonl. The entrypoint starts as root, chowns /data to node (and creates /data when no volume is mounted), then su-exec runs the server as node. Mount a volume to keep the usage log:

docker run --env-file .env -p 8787:8787 -v advan-data:/data advan

A development .env copied from .env.example sets HOST=127.0.0.1, which hides the port from outside the container. For a published port, set HOST=0.0.0.0 in that env file or pass -e HOST=0.0.0.0. Fly sets HOST in fly.toml.

The image runs the HTTP server only. Referral setup scripts run from a checkout (npm install includes the Jupiter referral SDK as a dev dependency).

Claude Desktop and Cursor

Paid tools need an x402-aware client. Claude Desktop and Cursor will see a payment-required (or payments-unconfigured) error for token_risk and wallet_portfolio. Use them for get_quote and build_swap_tx, and use scripts/e2e-devnet-x402.ts or createx402MCPClient for paid tools.

Claude Desktop claude_desktop_config.json:

{

"mcpServers": { "advan": { "command": "node", "args": ["/absolute/path/to/advan/dist/index.js"], "env": { "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com", "JUPITER_API_KEY": "", "JUPITER_REFERRAL_ACCOUNT": "", "JUPITER_REFERRAL_FEE_BPS": "50", "JUPITER_REFERRAL_TOKEN_ACCOUNT_SOL": "", "JUPITER_REFERRAL_TOKEN_ACCOUNT_USDC": "", "JUPITER_REFERRAL_TOKEN_ACCOUNT_USDT": "", "MAX_SLIPPAGE_BPS": "300", "MAX_TRADE_USD": "1000", "X402_PAY_TO": "", "X402_PRICE_USD": "0.01", "X402_NETWORK": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", "CDP_API_KEY_ID": "", "CDP_API_KEY_SECRET": "" } } } }

Cursor .cursor/mcp.json uses the same mcpServers object. During development you can point command at npx with args ["tsx", "src/index.ts"] from the repo root.

HTTP API

POST bodies are JSON. Free routes return the tool result. Paid routes answer 402 with PAYMENT-REQUIRED until the client retries with PAYMENT-SIGNATURE (x402 V2). A browser without a wallet gets the facilitator paywall HTML; API clients that send Accept: application/json also get a JSON body from unpaidResponseBody.

| POST | /v1/get_quote | `{ "inputMint",