SDK quickstart
Install the TypeScript SDK, initialize the API client, and cast your first vote. The SDK talks only to the Vocdoni SaaS API - never the blockchain directly.
The TypeScript SDK is the client-side half of an integration: it runs in the voter's browser to authenticate against the Credential Service Provider (CSP), encode the ballot and sign the vote transaction. It talks only to the Vocdoni SaaS API - it never reaches the chain directly. For the server-side lifecycle (organizations, members, censuses, processes and results) use the REST API; see SDKs and tools for when to use each.
This page is the bare minimum to get a client running. For the complete casting flow, see Casting votes.
Two small packages, not one monolith
The SDK ships as tree-shakeable packages that replace the older @vocdoni/sdk:
@vocdoni/api-client (typed HTTP client for the SaaS API) and @vocdoni/api-voting (CSP auth,
ballot encoding and vote signing). The api-client surface is still evolving - check the
SDK repository for the current method names.
Install
Add the two packages with your package manager of choice.
npm install @vocdoni/api-client @vocdoni/api-voting
pnpm add @vocdoni/api-client @vocdoni/api-voting
yarn add @vocdoni/api-client @vocdoni/api-voting
Initialize the client
Create a VocdoniApiClient pointing at the SaaS API. For public voter flows you don't need a token;
pass one only for authenticated (integrator or logged-in user) calls.
import { VocdoniApiClient } from '@vocdoni/api-client'
const client = new VocdoniApiClient({ apiUrl: 'https://saas-api-stg.vocdoni.net' })
The client exposes typed sub-clients for each part of the API - client.elections,
client.organizations, client.jobs and client.auth. client.elections covers the whole
/processes resource: the public process and question reads, the authoring writes, the voter CSP
flow and the vote relay.
client.processes is now client.elections
Earlier releases exposed a second client.processes sub-client for the voter CSP calls. Both
wrapped the same /processes/{id} endpoints with the same auth behaviour, so they were merged
into client.elections. client.processes still resolves to the very same instance as a
deprecated alias and is removed in the next major: migrating is a find and replace of
client.processes. for client.elections., with no signature changes.
Cast a vote
Casting adds @vocdoni/api-voting on top of the client. Every vote follows the same path:
authenticate once against the process census, check the voter's per-question eligibility, get a CSP
signature for that question's election, then build and relay the transaction. This is the condensed
version - Casting votes covers 2FA censuses, encrypted questions
and error handling.
import { VocdoniApiClient } from '@vocdoni/api-client'
import { EphemeralSigner, VotingClient } from '@vocdoni/api-voting'
const client = new VocdoniApiClient({ apiUrl: 'https://saas-api-stg.vocdoni.net' })
const voting = new VotingClient({ client })
// Both reported by the (public) process read.
const processId = '<processId>'
const chainId = '<chainId>'
// 1. Authenticate once against the process census (auth-only census - no 2FA step)
const { authToken } = await client.elections.authStep0(processId, { memberNumber: '42' })
// 2. Check the voter's standing - census membership plus, per question,
// eligibility and that question's on-chain election id (upstreamId)
const { belongsToProcess, questions } = await client.elections.check(processId, { authToken })
const question = questions.find((q) => q.canVote && !q.hasVoted)
if (!belongsToProcess || !question?.upstreamId) throw new Error('Cannot vote')
// 3. Get a CSP signature over a fresh ephemeral address for that question's election
const signer = new EphemeralSigner()
const { signature, weight } = await client.elections.sign(processId, {
authToken,
electionId: question.upstreamId,
payload: signer.address,
})
// 4. Build, relay and poll for the vote nullifier
const jobId = await voting.vote({
processId: question.upstreamId, // the vote goes to the question's election
chainId,
choices: [0],
signer,
cspSignature: signature,
cspWeight: weight,
})
const job = await client.jobs.waitFor(jobId)
console.log('voteID:', job.result?.voteID)
Building with React
@vocdoni/react-providers wraps the client in context providers and hooks that authenticate,
sign and relay for you, and @vocdoni/react-components adds unstyled UI on top. See the
SDK repository for the React packages.
AI agent skills
If you build with an AI coding agent, Vocdoni publishes Agent Skills - focused guides the agent loads on demand so it writes correct Vocdoni code without guessing the API shapes. The ones most relevant to the SDK:
- vocdoni-integrator-sdk - the SaaS-first flow: API client, CSP auth, vote relay, job polling and React providers. Authored in the integrator SDK repo.
- vocdoni-ballot-protocol - how a ballot encodes and how the results matrix aggregates per voting type.
They are packaged as a Claude Code plugin marketplace, and installable via npx for any client that reads a skills directory (Cursor, Cline, Zed and similar):
# Claude Code: add the marketplace, then install the plugin
claude plugin marketplace add vocdoni/skills
claude plugin install vocdoni-integrator-sdk@vocdoni
# Any skills-directory client
npx @vocdoni/skills install