Docs

Valta Docs

Installation

Install

bash
npm install valta-sdk

Requirements

  • Node.js 18 or later
  • TypeScript 5.0+ recommended

Works in Next.js, Express, Fastify, plain Node.js, and Bun.

Environment setup

Add your API key to your environment. Never commit it to git.

bash
# .env.local (gitignored)
VALTA_API_KEY=sk_valta_...

Initialize the client

ts
import { ValtaClient } from 'valta-sdk'

const valta = new ValtaClient({
  apiKey: process.env.VALTA_API_KEY,
  baseUrl: 'https://valta.co/api/v1', // optional — defaults to production
})

ESM and CommonJS

ts
// ESM
import { ValtaClient } from 'valta-sdk'

// CommonJS
const { ValtaClient } = require('valta-sdk')

TypeScript types

The SDK exports the following types:

TypeDescription
AgentAgent object returned by create, get, and list.
AgentRunResult of an agent run, including status and summary.
PolicySpending policy with all limit and restriction fields.
WalletInfoWallet balance, currency, and status.
AuditEntrySingle audit trail entry with hash chain fields.
ApiKeyAPI key metadata (never includes the full key value).
PaginatedResponse<T>Generic paginated wrapper with data, total, and page.

Error handling

All SDK methods throw ValtaError on non-2xx responses.

ts
import { ValtaClient, ValtaError } from 'valta-sdk'

const valta = new ValtaClient({ apiKey: process.env.VALTA_API_KEY })

try {
  const agent = await valta.agents.get('invalid-id')
} catch (err) {
  if (err instanceof ValtaError) {
    console.log(err.status)  // 404
    console.log(err.code)    // 'NOT_FOUND'
    console.log(err.message) // 'Agent not found'
  }
}

Error codes

CodeHTTP statusDescription
UNAUTHORISED401API key is missing or invalid.
FORBIDDEN403Key is valid but lacks permission for this action.
NOT_FOUND404The requested resource does not exist or is not owned by your account.
RATE_LIMIT_EXCEEDED429Too many requests. Back off and retry.
CREDITS_EXHAUSTED402No credits remaining. Resets on the 1st of the month.
AGENT_FROZEN403Agent is frozen. Unfreeze before running.
POLICY_VIOLATION403Action blocked by a spending policy rule.
APPROVAL_REQUIRED202Action requires human approval before it can proceed.
INVALID_REQUEST400Missing or malformed request parameters.
SERVER_ERROR500Unexpected server error. Contact support if it persists.

Next steps