Give your AI agent a policy-enforced Solana wallet.

What to give your AI agent

After selecting a hosted agent in the dashboard, copy the generated handoff card. The minimum secret your agent needs is the API key.

AGENTWALLET_API_KEY=<copy-from-dashboard>

AGENTWALLET_BASE_URL=https://agentwallet-web.vercel.app

Once the agent has those values, policy changes do not require a new SDK snippet. Update policy in AgentWallet; the next agent payment uses the latest on-chain policy account.

Use from a Node or TypeScript agent

import { AgentWallet } from "@agentwallet/sdk";

const wallet = new AgentWallet({
  baseUrl: process.env.AGENTWALLET_BASE_URL ?? "https://agentwallet-web.vercel.app",
  apiKey: process.env.AGENTWALLET_API_KEY!
});

const me = await wallet.getAgent();
console.log("Agent wallet:", me.agent.publicKey);
console.log("Ready:", me.status.readyForPayments);

const capabilities = await wallet.getCapabilities();
console.log("Allowed recipients:", capabilities.allowed.recipients);
console.log("Remaining budget:", capabilities.spend.remainingBudgetUnits);

const payment = await wallet.pay({
  recipient: "6tNgWp8rq4UJ77q2cZ8WPeBn5eUDhcSuC5nSEXd1W8yA",
  amount: "1"
});

console.log("Explorer:", payment.explorerUrl);

Let agents check readiness before spending

curl "https://agentwallet-web.vercel.app/api/agent-wallet/setup-status" \
  -H "Authorization: Bearer $AGENTWALLET_API_KEY"

// Example response:
{
  "setup": {
    "ready": false,
    "missing": ["policy_pda"],
    "ownerActionRequired": true,
    "nextAction": "Ask the owner to initialize or update the on-chain policy for this hosted agent.",
    "availableActions": ["get_wallet_status", "get_audit_log"]
  }
}

Let agents discover their exact boundaries

curl "https://agentwallet-web.vercel.app/api/agent-wallet/capabilities" \
  -H "Authorization: Bearer $AGENTWALLET_API_KEY"

// Example response:
{
  "ok": true,
  "policy": {
    "status": "active",
    "pda": "<policy-pda>"
  },
  "allowed": {
    "recipients": ["6tNgWp8rq4UJ77q2cZ8WPeBn5eUDhcSuC5nSEXd1W8yA"],
    "tokenMints": ["<allowed-token-mint>"]
  },
  "spend": {
    "maxPerPaymentUnits": "3000000",
    "remainingBudgetUnits": "6000000",
    "approvalThresholdUnits": "2000000"
  },
  "supportedActions": ["simulate_payment", "request_payment", "get_audit_log"]
}

Use capabilities before planning actions. It tells the agent what it controls, what it can pay, which tokens are allowed, and whether spending is currently paused.

Use from any agent framework

curl "https://agentwallet-web.vercel.app/api/agent-wallet/me" \
  -H "Authorization: Bearer $AGENTWALLET_API_KEY"

curl "https://agentwallet-web.vercel.app/api/agent-wallet/capabilities" \
  -H "Authorization: Bearer $AGENTWALLET_API_KEY"

curl -X POST "https://agentwallet-web.vercel.app/api/agent-wallet/simulate-payment" \
  -H "Authorization: Bearer $AGENTWALLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "6tNgWp8rq4UJ77q2cZ8WPeBn5eUDhcSuC5nSEXd1W8yA",
    "amount": "5"
  }'

curl -X POST "https://agentwallet-web.vercel.app/api/agent-wallet/pay" \
  -H "Authorization: Bearer $AGENTWALLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "6tNgWp8rq4UJ77q2cZ8WPeBn5eUDhcSuC5nSEXd1W8yA",
    "amount": "1"
  }'

The hosted agent record stores the program ID, policy PDA, token mint, and decimals. Advanced callers can send explicit fields, but the on-chain policy remains the final authority.

Plan before moving tokens

const preview = await wallet.simulatePayment({
  recipient: "6tNgWp8rq4UJ77q2cZ8WPeBn5eUDhcSuC5nSEXd1W8yA",
  amount: "5"
});

if (preview.decision === "approved") {
  await wallet.pay({ recipient: "6tNgWp8rq4UJ77q2cZ8WPeBn5eUDhcSuC5nSEXd1W8yA", amount: "5" });
}

if (preview.decision === "requires_approval") {
  console.log(preview.suggestedAction); // request_owner_approval
}

Simulation reads the on-chain policy account and returns the same structured codes as a real payment attempt, without signing or sending a Solana transaction.

Handle rejections programmatically

{
  "ok": false,
  "error": "Rejected: that recipient wallet is not on the allowed list.",
  "code": "RECIPIENT_NOT_ALLOWED",
  "message": "Recipient wallet is not on the allowed list.",
  "humanMessage": "That recipient wallet is not on the allowed list.",
  "agentMessage": "Choose an allowed recipient or ask the owner to update the policy.",
  "suggestedAction": "request_owner_policy_update"
}

Agents should branch on `code` and `suggestedAction`, not free-form text.

Above-threshold payments

If the agent requests a payment above the autonomous approval threshold, AgentWallet creates an approval request instead of moving tokens. The owner approves or rejects in the dashboard. Approved payments execute automatically with the hosted agent wallet.

Pay APIs without static API keys

const response = await wallet.fetch("https://agentwallet-web.vercel.app/api/demo-merchant/resource");

// The merchant can return 402 + PAYMENT-REQUIRED.
// AgentWallet settles through the policy engine, then retries with PAYMENT-SIGNATURE.
console.log(await response.json());

Let tools discover AgentWallet

AgentWallet exposes an OpenAPI 3.1 document for agent frameworks, API clients, and tool-generation flows.

https://agentwallet-web.vercel.app/api/openapi.json

Use AgentWallet as native agent tools

{
  "mcpServers": {
    "agentwallet": {
      "command": "npx",
      "args": ["agentwallet-mcp"],
      "env": {
        "AGENTWALLET_BASE_URL": "https://agentwallet-web.vercel.app",
        "AGENTWALLET_API_KEY": "<hosted-agent-api-key>"
      }
    }
  }
}

The MCP server exposes tools for wallet status, capabilities, allowed recipients, allowed tokens, payment simulation, payment execution, and audit history.

Common setup misses

• Invalid API key: rotate the selected hosted agent key and update the agent secret.
• Wallet not funded: send devnet SOL to the hosted wallet before minting or transferring tokens.
• Recipient rejected: add the recipient wallet to the policy and update the on-chain policy.
• Token rejected: add the token mint to the allowlist and fund the agent token account.
• Policy missing: initialize the selected agent policy account before calling the SDK.