How to onboard a new AI agent with a test-mode wallet and API key

What good onboarding should prove

A new agent should prove four things before it reaches live mode: it can authenticate, it can hold a wallet ID, it can create or receive a test payment, and it can stay inside a spending policy.

That sounds small, but it is the difference between a demo and a product. If onboarding stops at account creation, the builder still has to figure out keys, wallets, token units, funding, and verification alone. Each unresolved step lowers the chance that they ever reach a production payment.

ROI for product teams

The ROI is shorter time to first value. A user who creates a wallet and sends a test payment in the first session is much more likely to integrate the API than a user who only reads docs.

A tight onboarding flow also reduces support burden. Instead of answering the same questions about API keys, devnet funding, and wallet IDs, the product guides the user through the path once and records enough state for the dashboard to explain what happened.

Recommended onboarding path

• Create the account and show the API key once.
• Start in test mode on Solana devnet.
• Create a wallet with a human label such as research-agent or telegram-bot.
• Credit test USDC or request devnet SOL where needed.
• Set a low spending limit before any automated send path.
• Run one test payment and show a receipt or status update.
• Only then explain live mode and mainnet funding.

Create a test-mode wallet

The wallet is the first durable object the agent can reason about. Store the wallet ID in your product database under the agent record. Do not ask the model to remember it in a prompt.

const wallet = await fetch("https://api.viaclave.com/v1/wallets", {
  method: "POST",
  headers: {
    "Authorization": "Bearer vc_test_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    label: "research-agent",
  }),
}).then((res) => res.json());

Store onboarding state

Treat onboarding as a state machine. That lets your UI show the next useful step and lets support see where a user got stuck.

type AgentOnboarding = {
  accountId: string;
  agentId: string;
  walletId?: string;
  apiKeySavedAt?: string;
  testFundsCreditedAt?: string;
  firstPaymentId?: string;
  liveModeEnabledAt?: string;
};

Add a limit before the first automated send

A new agent should not receive unlimited payment authority. Start with a small per-call and daily cap, then raise it only after the workflow is measured.

await fetch("https://api.viaclave.com/v1/wallets/" + wallet.id + "/limits", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer vc_test_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    per_tx_limit: 1000000,
    daily_limit: 5000000,
  }),
});

The first success moment

The first success moment should be visible: a test payment status, a receipt, or a clear webhook event. Do not hide this inside logs. The user needs proof that the agent can move money through the rail.

Once that works, the live-mode explanation is simple. Test mode proved the flow on devnet. Live mode uses the same product shape with live API keys, mainnet wallets, and real stablecoins.

Production checklist

• Never show API keys twice.
• Keep test mode and live mode visually distinct.
• Create wallets from backend-controlled flows, not from prompt text alone.
• Store wallet IDs and agent IDs in your database.
• Set limits before scheduled or autonomous sends.
• Use receipts and webhooks to confirm the first payment.