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 installnpm run buildcp .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.

amount is an integer string in base units. Addresses are base58. slippageBps is an integer 0–10000, then capped by MAX_SLIPPAGE_BPS.

Example:

curl -s http://127.0.0.1:8787/healthzcurl -s http://127.0.0.1:8787/healthcurl -s http://127.0.0.1:8787/v1/get_quote \  -H 'content-type: application/json' \  -d '{"inputMint":"So11111111111111111111111111111111111111112","outputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"10000000"}'

/stats summarizes the JSONL usage log: calls, calls today (UTC), errors, fee_check_failure rows, x402 verifies / settlements / failed settlements, USDC base units received, and an estimate of integrator referral fees (80% of feeBps on the fee mint). On-chain accrued fees are the referral token-account balances (referral.jup.ag or npm run claim:referral), not that estimate.

Each log line is one JSON object with kind of tool, fee_check_failure, referral_requote, x402_settlement, x402_verification, facilitator_failover, or facilitator_recovered, plus tool, ts, latencyMs, success, error, errorCode, paymentStatus, facilitator, feeBps, feeMint, estimatedIntegratorFeeRaw, and usdcAtomic where they apply. /health reports the data RPC origin and the x402 RPC origin separately.

Referral setup

From a checkout (needs the dev dependency @jup-ag/referral-sdk):

REFERRAL_PAYER_PUBKEY=<your wallet> REFERRAL_NAME=advan npm run setup:referral

The script prints unsigned transactions (referral account, then wSOL, USDC, and USDT token accounts) using Jupiter's referral project DkiqsTrw1u1bYFumumC7sCG2S8K25qc2vemJFHyW2wJc. Sign and send them in order from that wallet. Put the printed referral account and token accounts into .env. Optional REFERRAL_MINTS adds more fee mints. REFERRAL_PARTNER_PUBKEY defaults to the payer.

REFERRAL_PAYER_PUBKEY=<partner> JUPITER_REFERRAL_ACCOUNT=<account> npm run claim:referral

That prints unsigned claimAllV2 transactions. Nothing is signed in either script.

Devnet x402 test

1. Create a keypair and request devnet SOL only if you need it for the ATA setup. The x402 exact scheme uses the facilitator as the fee payer, so the buyer needs devnet USDC, not SOL, to pay for a call.
2. Get devnet USDC from the Circle faucet (Solana Devnet), mint 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU.
3. Create the payee USDC account (unsigned; sign it yourself). This script uses X402_RPC_URL, or the public RPC for X402_NETWORK when that is unset. It does not read SOLANA_RPC_URL.

X402_NETWORK=solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 \X402_PAY_TO=<payee pubkey> \REFERRAL_PAYER_PUBKEY=<account that pays rent> \X402_RPC_URL=https://api.devnet.solana.com \npm run setup:payto-ata

4. Start the HTTP server with X402_PAY_TO and X402_NETWORK (devnet). Leave SOLANA_RPC_URL on mainnet if token_risk should read mainnet mints. Set X402_RPC_URL only when the public devnet RPC is not the one you want; when it is unset Advan derives https://api.devnet.solana.com from the devnet CAIP id. Do not point X402_RPC_URL at mainnet. Use CDP keys or leave them unset (PayAI, free on devnet). X402_PRICE_USD can be 0.01 or 0.005.
5. Pay from the buyer keypair. X402_CLIENT_RPC_URL is the buyer's RPC for the USDC transfer. The public devnet RPC is often unreachable, so set one you can use. The script pays for token_risk and wallet_portfolio. E2E_MINT defaults to devnet USDC (4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU) when X402_NETWORK is devnet, and to mainnet USDC otherwise.

SOLANA_KEYPAIR_PATH=./devnet-payer.json \ADVAN_HTTP_URL=http://127.0.0.1:8787 \X402_NETWORK=solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 \X402_CLIENT_RPC_URL=https://api.devnet.solana.com \npm run e2e:devnet

token_risk and wallet_portfolio read SOLANA_RPC_URL (mainnet by default). The payment blockhash comes only from X402_RPC_URL. Native SOL in a devnet portfolio is still priced from Jupiter's mainnet wSOL market, because devnet has no SOL/USD book. The response field sol.priceSource says which one was used.

MCP smoke test (stdio and Streamable HTTP: lists tools, optionally hits Jupiter for get_quote and build_swap_tx, and parses the unpaid token_risk payment-required payload):

npm run smoke:mcpSKIP_LIVE=1 npm run smoke:mcp

Development

npm run lintnpm run typechecknpm testnpm run build

CI runs those four steps on Node 20. Unit tests mock Jupiter, RPC, and facilitators.

Open decisions

These are configuration, not hardcoded wallets:

• Referral fee defaults to the 50 bps minimum. Raising it (up to 255) earns more and makes quotes less competitive. Jupiter keeps 20%.
• x402 price defaults to $0.01 so a PayAI mainnet settlement ($0.00133) stays under about 13% of the price. Set X402_PRICE_USD=0.005 if you accept a tighter margin; mainnet will warn at the 5× check.
• Package name advan-mcp looked free on 2026-10-25. .github/workflows/npm-publish.yml publishes it on a GitHub release (or a manual workflow run). Publishing still needs an npm token stored as NPM_TOKEN.
• Hosting for Fly.io is in fly.toml and docs/DEPLOY-FLY.md. The Dockerfile listens on 8787. Put a real RPC URL in SOLANA_RPC_URL before production traffic; api.mainnet-beta.solana.com is rate-limited.
• CDP keys are free to create. The first 1,000 successful settlements each month are free, then $0.001. Whether devnet settlements count toward that quota is not stated in the CDP docs.
• PayAI includes 1,000 free credits total (not monthly). Devnet settlements are free. Topping up is a spending decision.
• Self-broadcast default is off so JupiterZ can compete. Turn SWAP_SELF_BROADCAST_DEFAULT on if every client broadcasts its own transaction.
• FEE_CHECK_MODE defaults to fail. Use warn only if you would rather return a transaction whose integrator fee did not stick.
• X402_PRICE_GUARD defaults to warn. Set refuse in production if a too-low price should stop the process.