solana-agent-kit-vaultbags

A Solana Agent Kit v2 plugin that lets any agent read the VaultBags autonomous real-world-asset treasury and run its allocation model.

VaultBags turns Bags trading fees into tokenized gold, the S&P 500 and US treasuries that holders claim directly. Every day at 00:00 UTC it reads live market data, freezes that day's buy proportions inside a strict 23-43% band, and stamps the decision on-chain. This plugin exposes that surface as agent tools.

Everything here is read-only public data over HTTPS. The plugin holds no key, never signs, never moves funds, and needs no auth.

Install

npm install solana-agent-kit-vaultbags

solana-agent-kit (v2) and zod are peer dependencies; they are already present in any Solana Agent Kit project, so nothing new is pulled into your tree.

Usage

Attach it to your existing agent (the wallet, rpcUrl and config come from your own Solana Agent Kit setup; this plugin never reads or uses the wallet):

import { SolanaAgentKit, createVercelAITools } from "solana-agent-kit";
import VaultBagsPlugin from "solana-agent-kit-vaultbags";

const agent = new SolanaAgentKit(wallet, rpcUrl, config).use(VaultBagsPlugin);

// Call a method directly:
const today = await agent.methods.getTodaysAllocation();

// Or expose the actions to your model (Vercel AI SDK, LangChain, OpenAI, ...):
const tools = createVercelAITools(agent, agent.actions);

Or skip the framework entirely: every method also works standalone, with no wallet, no keys and no configuration.

import { methods } from "solana-agent-kit-vaultbags";

const today = await methods.getTodaysAllocation();

Tools

| Action | Method | What it returns | | --- | --- | --- | | VAULTBAGS_GET_TODAYS_ALLOCATION | getTodaysAllocation() | Today's gold / S&P 500 / US treasuries buy proportions, the 23-43% band, whether the decision is frozen, the rationale, and the on-chain receipt. | | VAULTBAGS_GET_DAILY_BRIEFING | getDailyBriefing() | Today's market note explaining the allocation, plus weights and receipt. | | VAULTBAGS_GET_TREASURY_STATS | getTreasuryStats() | Live per-asset balances and USD values, total vault value, total paid to holders, holder count, cycles and fees processed. | | VAULTBAGS_GET_DECISION_HISTORY | getDecisionHistory({ days }) | Recent daily decisions (newest first) with weights, rationale and receipts. days 1-30, default 14. | | VAULTBAGS_GET_MARKET_SIGNALS | getMarketSignals() | The quantitative signals behind today's allocation, each with its per-asset read. Numbers only. | | VAULTBAGS_GET_BRAIN_VS_FLAT | getBrainVsFlat() | Honest track record: the daily allocation line versus a fixed even split, with the edge reported either way. | | VAULTBAGS_SIMULATE_ALLOCATION | simulateAllocation({ ...signals }) | Runs the vault's model on your own market inputs and returns the weights it would choose. Deterministic, bounded, not advice. | | VAULTBAGS_GET_PROJECTS | getProjects() | Every treasury currently running on VaultBags. | | VAULTBAGS_GET_PROJECT_TREASURY | getProjectTreasury({ mint }) | One integrated project's live treasury by SPL token mint. | | VAULTBAGS_GET_AGENT | getAgent({ mint }) | Evaluate any launched token as an agent: Autonomy Score split into inherited protocol guarantees vs its own earned record, plus passport and treasury. | | VAULTBAGS_GET_VAULT_DOCS | getVaultDocs() | Condensed protocol documentation and live surface links. | | VAULTBAGS_LIST_RWAS | listRwas({ category?, issuer? }) | The certified registry of openly transferable tokenized RWAs on Solana (gold, US Treasuries, US equities/ETFs), every mint verified against the issuer's own domain. | | VAULTBAGS_GET_RWA | getRwa({ query }) | One certified RWA resolved by symbol or mint: verified identity plus a live market read. Protects agents from impersonator mints. | | VAULTBAGS_GET_PROTOCOL_METER | getProtocolMeter() | The Meter: the protocol's consolidated live numbers, every section with its verification URL. | | VAULTBAGS_GET_AUTONOMY | getAutonomy() | The vault agent's Autonomy Score and the verifiable facts behind it. | | VAULTBAGS_GET_AGENT_PASSPORT | getAgentPassport() | The agent's portable machine-readable passport (identity, surfaces, receipts). | | VAULTBAGS_GET_RWA_PERFORMANCE | getRwaPerformance() | The vault's real cost basis and return per RWA position since purchase, in USD and SOL terms. | | VAULTBAGS_GET_SHADOW_VS_BRAIN | getShadowVsBrain() | The shadow language model's daily calls measured against the deterministic brain. | | VAULTBAGS_GET_RECENT_CYCLES | getRecentCycles({ limit? }) | The latest distribution cycles with their on-chain receipts. limit 1-20, default 5. | | VAULTBAGS_GET_MONTHLY_REPORTS | getMonthlyReports({ months? }) | The agent's closed books, one per calendar month, each committed on-chain. months 1-24, default 12. | | VAULTBAGS_GET_PAYOUT_INTEGRITY | getPayoutIntegrity() | Every payout ever recorded, looked up on Solana and counted: accepted, rejected, or no longer in the answering node's history. Recomputed on read. allLanded is true only when every one was found AND accepted. Serves nothing rather than a figure it could not verify in full. | | VAULTBAGS_GET_LOCK_TIER | getLockTier({ days?, wallet? }) | The tier a lock term reaches, or the one a wallet holds. Both optional and independent. Derived from the term signed for, never stored, and it grants nothing: the boost multiplier does not read it, and the same term reaches the same tier at any balance. | | VAULTBAGS_GET_TREASURY_HISTORY | getTreasuryHistory({ days?, points? }) | The treasury's value and per-asset balances over time. Samples span the WHOLE window, not its newest end, so a 90-day request describes 90 days. Descriptive history, never a projection. | | VAULTBAGS_GET_HOLDER_DISTRIBUTION | getHolderDistribution() | Distinct holding wallets (not token accounts; protocol wallets and pools excluded), the change over a day and a week, how many are locking, and how concentrated supply is. Aggregates only, no addresses. Concentration is null rather than approximated when its scan could not complete. | | VAULTBAGS_GET_RECENT_ACTIVITY | getRecentActivity() | Recent trading for the last day and week: trades, buys, sells and distinct buyers, sellers and traders. truncated marks a window whose counts are a floor rather than a total. | | VAULTBAGS_GET_PROOF_OF_RESERVES | getProofOfReserves() | Proof of Reserves: the reserve wallets, their certified issuers and live on-chain balances, plus decision receipts and value paid to holders. | | VAULTBAGS_VERIFY_CLAIM | verifyClaim({ tx }) | Verify one holder claim against the on-chain Merkle root: the committed record, its proof, the day's root and the on-chain memo. Recompute it yourself; the guarantee is on-chain. | | VAULTBAGS_VERIFY_DECISION | verifyDecision({ date? }) | Verify one daily allocation decision against the hash stamped on-chain that day: the payload the receipt commits to, both hashes, the anchoring transaction and the wallet that must have signed it. Omit date for today. | | VAULTBAGS_GET_LIQUIDITY | getLiquidity() | The liquidity the protocol built into its own pool and whether any of it can be withdrawn. lock.allLocked is read from the position itself, true only when it reports zero unlocked liquidity. builtIntoLiquidity is a cost basis at each deposit's own hour; positionNow is what it represents today. feesCompounded is what the locked position earned and had put back in. readAt, positionReadAt and positionNow.pricedAt say when each part was read. | | VAULTBAGS_GET_SUPPLY | getSupply() | Both figures called "supply": marketSupply (total minted, what market caps use) and distributedSupply (pool balances excluded, what holder shares and the lock boost use). Using the wrong one silently produces a wrong percentage. | | VAULTBAGS_GET_RAFFLE | getRaffle() | The holder raffle's public state: window, weighted tickets, participants, prizes and claim grace. Tickets weight how long a holder held, not a balance at one instant. Randomness comes from a public beacon round recorded when the ticket list is frozen and emitted only after it. Aggregate only. | | VAULTBAGS_GET_AUTONOMY_SPEC | getAutonomySpec() | The rules behind the Autonomy Score, published so the number can be checked instead of believed: every dimension, its weight, the formula, where its data comes from and how independently verifiable it is. Names what the score does not claim, and marks the one dimension that is self-asserted. | | VAULTBAGS_SIMULATE_LOCK_BOOST | simulateLockBoost({ amount? }) | Estimate the $VAULT lock boost with live data: the share of circulating supply locked now, the shared multiplier that produces (the payout cron's own formula, capped at 1.5x), and what both become after locking N more. The multiplier is global, so locking more applies the boost to more tokens rather than raising the number. | | VAULTBAGS_VERIFY_DAY | verifyDay({ period? }) | Verify a whole day of the claim ledger against its Merkle root stamped on Solana: every committed claim, the recomputed root, the stamped root, whether they match, and the treasury signer to check. Omit period for the latest stamped day. | | VAULTBAGS_VERIFY_RECEIPT | verifyReceipt({ receipt }) | Verify a payment receipt from the X-X402-Receipt header of a paid call: the RS256 signature against the key published at /.well-known/jwks.json, every claim against its own rules, and the destination against the lane's live terms. issuedByVaultBags says whether VaultBags issued it as it reads, and current whether it is still inside its one-hour time box (a lapsed receipt is genuine but no longer a live proof). paymentProvenHere is always false and says so: a signature proves who issued the receipt, the transaction on Solana proves the payment. | | VAULTBAGS_GET_STRATEGIES | getStrategies() | Every vault strategy: the four presets plus each distinct strategy a live project has frozen. A strategy is a signed selection of 2-4 certified real-world assets, each at least 15%, identified by the hash of that selection. Presets run as live paper strategies, stamped on-chain before adoption, so the record is verifiable rather than narrated. | | VAULTBAGS_GET_STRATEGY | getStrategy({ strategy }) | One strategy in depth: its signed asset selection, which tokens adopted it, and its recent daily decisions with weights, convictions and on-chain memo receipts. Identify it by preset id (classic, growth, hard-money, income) or by its 64-hex key. |

Configuration

By default the plugin talks to https://vaultbags.app. To point it elsewhere (for local testing), set VAULTBAGS_API_URL in the agent config:

const agent = new SolanaAgentKit(wallet, rpcUrl, {
  OTHER_API_KEYS: { VAULTBAGS_API_URL: "http://localhost:3000" },
}).use(VaultBagsPlugin);

Notes

• The tool names, schemas and descriptions mirror the VaultBags MCP server verbatim, so an agent sees the same contract whether it connects over MCP or through this plugin.
• There are paid resources this plugin deliberately does not call. Beyond the free tools above, VaultBags sells three things over x402: a question to its analyst, the full receipted decision ledger, and a live batch read of the certified RWA registry. Each answers HTTP 402 with its own terms when called bare. This package holds no keys and pays for nothing, so it never settles one; an agent that pays with its own x402 client can bring the receipt back here and check it with verifyReceipt.
• simulateAllocation runs the model on inputs you supply; it is a compute helper, not a read of the vault's own live decision. Nothing it returns predicts returns or moves funds.
• All data is informational. This plugin does not provide financial advice.

Links

• Agent surface: https://vaultbags.app/agent
• Daily briefing: https://vaultbags.app/briefing
• Docs: https://vaultbags.app/docs