DEVELOPER GUIDE · RUNTIME

Connect an Agent Runtime

A Runtime Agent is the process that calls Spendkit while doing work. You can implement it yourself or use an AI coding assistant. Both paths use the same OAuth token endpoint, MCP tools, and a trusted transaction sender for the bound Payment Wallet.

Start with code

Copy a JavaScript, Python, Go, or C++ example → The default examples connect, read the Agent and Policy, and preview a payment. Add your business decision and bound-wallet sender at the marked comments. Use the reference below when you need to understand or extend a call.

BUILD IT YOURSELFCopy and adapt a client

Choose a complete example, replace the marked business logic, and connect a wallet signer for payment. Use the tool reference for each input and output.

BUILD WITH AIHave a coding Agent adapt it

Give the same example and your project to a coding assistant. Its code runs in your Runtime; the assistant itself does not need payment credentials. AI development steps →

Before integration

Complete the dashboard setup: Agent, verified Payment Wallet, and ready onchain Spending Policy.
Use Connect Agent to create or update Full Runtime Access. Copy its Client ID and Client Secret into protected Runtime configuration.
Make the bound wallet available to your trusted signing process. It needs test USDG, native gas, and the Router allowance established during setup. Never expose its private key to the model or Spendkit Server.

Endpoints and credentials

Base URLhttps://spendkit-alpha.vercel.app

OAuth tokenPOST /oauth/token

MCPPOST /mcp

The base URL is the public address of this Spendkit service; it is not issued in the dashboard. Get the Client ID and Client Secret from AI Agents → your Agent → Connect Agent. Set up and verify the Payment Wallet there too. Its private key, if your signer uses one, comes from your own wallet or protected key store—not from Spendkit. See the value-by-value setup guide →

Exchange the connection's client_id and client_secret with grant_type=client_credentials. The token response includes access_token, token_type, expires_in, and scope. Use the Bearer token for MCP and refresh it before expiry. Do not persist the short-lived access token as permanent configuration. See the exact request and response →

# Public service address; no dashboard setup needed
SPENDKIT_BASE_URL=https://spendkit-alpha.vercel.app
# Dashboard → AI Agents → your Agent → Connect Agent
SPENDKIT_CLIENT_ID=<connection-client-id>
SPENDKIT_CLIENT_SECRET=<connection-client-secret>
# Your verified wallet address and your own local signer (reference Agent only)
PAYMENT_WALLET_ADDRESS=<bound-wallet-address>
PAYMENT_WALLET_PRIVATE_KEY=<local-secret-only>

PAYMENT_WALLET_PRIVATE_KEY is used only by the reference local Agent's private-key signer. Other trusted wallet signers can be used. The key belongs only in your protected Runtime secret store; never enter it in the dashboard. The reference local Agent derives its address from that key and fails closed if it differs from the wallet bound to the Agent.

First read-only check

Discover the MCP server, list tools, and call spendkit_get_connection. Confirm the returned Agent, network, bound Payment Wallet, and readiness. Then call spendkit_get_policy and preview a small proposed payment. These steps do not broadcast a blockchain transaction. The tool reference lists each input and output.

When you enable payment submission

Request authorization only for an actual intended payment. The result contains intentId, a signed authorization, and an exact transaction with chainId, from, to, data, and value. Verify transaction.from equals the bound wallet and submit that exact transaction from the same wallet. Record its hash and query status. Follow the complete sequence →

Reference implementation

The repository's local AI Agent shows credential refresh, wallet matching, confirmation, transaction submission, and status handling. A new integration should first complete the read-only check, then separately enable actual testnet payment.