Developers

Build on Chainvara in an afternoon

One REST API for wallets, transfers, payouts, tokens and compliance. Every call goes through the same policies, approvals and screening as the console, and every change reaches you as a signed webhook.

$ curl -X POST /api/v1/transfers …

201 transfer_8f2… pending_approval

webhook transfer.approved FOS-Signature ✓

webhook transfer.submitted 0x7a1…e04

webhook transfer.confirmed 12 confirmations

→ order #1042 marked paid

Quick start

1

Create a key

Sign up, open Developers and create a test key (fos_test_…). Test keys run on public test networks; live keys (fos_live_…) on mainnets.

2

Call the API

Send the key as a Bearer token. Add an Idempotency-Key to every POST so a retry never pays twice.

3

Listen

Register an https endpoint for webhooks, verify each signature, and react to transfer.confirmed.

curl https://www.chainvara.com/api/v1/transfers \
  -H "Authorization: Bearer $CHAINVARA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{ "wallet_id": "…", "asset": "USDC", "amount": "250", "destination": "0x…" }'

REST API

Base URL

https://www.chainvara.com/api/v1, JSON in and out.

Scoped keys

Each key has scopes (wallets:read, transfers:write…), an environment, an optional expiry and an optional IP allowlist. Only a hash is stored. Revoke anytime.

Idempotency

An Idempotency-Key on POST replays the original answer; a different body with the same key is refused.

Rate limits

Per key and per minute according to your plan, with X-RateLimit headers and Retry-After on 429.

Wallets

POST/walletsCreate a wallet (key_mode single, split or mpc) or one per end user with external_user_id
GET/walletsList wallets, filter by purpose, custody or external_user_id
GET/wallets/{id}/balancesBalances read from the chain
GET/wallets/{id}/transactionsIndexed on-chain history
POST/wallets/{id}/refresh-keysRenew both MPC key shares with your co-signer: same address, old shares void
POST/deposit-addressesEvery deposit address of one of your users in one idempotent call

Transfers and operations

POST/transfers/previewPolicy decision, fee and simulation; nothing is created
POST/transfersRequest a transfer (policy, approvals, screening, then signing)
GET/transfersNewest first; filter by status, wallet_id, external_id, tag; page with starting_after=next_cursor
GET/transfers/{id}Status, approvals, transaction hash
POST/transfers/{id}/cancelCancel before signing
POST/transfers/{id}/tagsReplace a transfer's accounting tags (list with ?tag=)
GET/networks/{id}/feesFee estimates per fee_level for a typical transfer
POST/transfers/{id}/speed-upStuck EVM, Bitcoin or Litecoin transaction: same transaction (same coins), higher fee
POST/transfers/{id}/cancel-onchainStuck EVM, Bitcoin or Litecoin transaction: replace it with one back to the wallet
POST/operationsTokens, NFT creation and transfers, staking, swaps, cross-chain USDC (CCTP), freeze and supply lock
POST/payoutsBatch payments from one wallet
GET/vaultsVault accounts (freezable groups of wallets)
POST/vaultsCreate a vault
POST/vaults/{id}/freezeFreeze a vault from your SIEM: nothing leaves it until unfrozen in the console
POST/wallets/{id}/vaultMove a wallet into a vault (or out with null)
GET/wallets/{id}/allowancesToken approvals that can still be used (ERC-20, NFT operators, Permit2), with what is at risk
POST/wallets/{id}/allowancesRevoke one approval: a contract call under your policy and co-signer
GET/policyThe policy in force, its version and history (policy as code)
POST/policy/impactReplay a candidate policy on the last 200 requests: what it would change
GET/addressesThe address book (trusted destinations, cooldown included)
POST/addressesAdd a trusted destination (scope addresses:write; screened, cooldown applies)
POST/addresses/{id}/revokeStop trusting a destination immediately
GET/reports/gainsRealized gains and positions with cost basis (FIFO or average cost)
POST/address-proofsSelf-hosted wallet: a message for its owner to sign, and the link to send them
POST/address-proofs/{id}/signatureRecord the owner's signature (checked against the address)
GET/address-proofsOwnership requests and their status

Chainvara network (between organizations)

POST/network/requestsAsk a connected organization to pay you, to your published address
POST/network/requests/{id}/payPay an incoming request (your policy and approvals apply)
POST/network/obligationsRecord what you owe or are owed; counts once the other side confirms
GET/network/positionsNet position per counterparty and asset
POST/network/settlementsSettle the whole net position with one transfer
GET/travel-rule/messagesTravel Rule data exchanged with network organizations

Embedded wallets (your users' devices)

POST/embedded/walletsJoint key generation with the user's device: Solana (FROST) or any EVM network (threshold ECDSA)
POST/embedded/signSign an approved transfer with the device, which checks the exact transaction first
POST/embedded/backupStore or fetch the device share's backup, encrypted under the user's recovery code

Data and compliance

GET/screeningSanctions check for any address
GET/screening/inboundScreening of the senders of your deposits
GET/pricesUSD prices of supported assets
GET/networksSupported networks and assets
GET/swap/quoteBest route and guaranteed minimum
GET/tokensTokens your organization issued
GET/reports/ledgerInflows, outflows and fees by period
GET/securitySecurity posture score and checks
GET/eventsEvent history (the same events as webhooks)
GET/audit?after=Audit trail in chain order, for your SIEM (scope audit:read)
GET/audit/verifyRecompute the audit hash chain; returns its head
POST/reserves/snapshotsProof of reserves: commit customer balances, read reserves
GET/reserves/snapshots/{id}/proofOne customer's inclusion proof

Errors use one shape: { "error": { "type", "code", "message", "request_id" } }. Every endpoint and field is in the API reference (also as an OpenAPI file).

TypeScript SDK

One dependency-free ES module for Node.js 18+ with full types, automatic retries on network errors and 5xx, idempotency keys and webhook verification. cv.eip1193(walletId, { rpcUrl }) is a standard EIP-1193 provider: use a vault wallet from viem, ethers or Hardhat, and every transaction or signature goes through your policy, approvals and co-signer (key scope contracts:write).

import { Chainvara } from "./chainvara.js";
const cv = new Chainvara(process.env.CHAINVARA_API_KEY);

// A deposit wallet for a customer.
const wallet = await cv.wallets.create({
  network: "solana", external_user_id: user.id,
});

const req = { wallet_id: treasury.id, asset: "USDC",
  amount: "250", destination: "@partner" };
const preview = await cv.transfers.preview(req);
if (preview.decision.outcome !== "deny") {
  await cv.transfers.create(req, { idempotencyKey: order.id });
}

Python SDK

One file, standard library only (Python 3.9+): the same resources, retries with backoff, idempotency keys, webhook and co-signer signatures. Drop it next to your code.

from chainvara import Chainvara, verify_webhook
cv = Chainvara(os.environ["CHAINVARA_API_KEY"])

wallet = cv.wallets.for_user(user.id, "solana")

t = cv.transfers.create(wallet_id=treasury_id, asset="USDC",
    amount="250", destination="@partner",
    idempotency_key=order.id)
cv.transfers.wait(t["id"])

event = verify_webhook(request.body,
    request.headers["fos-signature"], WEBHOOK_SECRET)

Go SDK

One file, standard library only (Go 1.21+), context-aware: the same resources, retries with backoff, stable idempotency keys, typed errors, webhook and co-signer signatures. Put it in a chainvara package of your module.

cv, err := chainvara.New(os.Getenv("CHAINVARA_API_KEY"))

t, err := cv.Transfers.Create(ctx, chainvara.TransferParams{
    WalletID: treasuryID, Asset: "USDC", Amount: "250",
    Destination: "@partner", IdempotencyKey: order.ID,
})
var apiErr *chainvara.Error
if errors.As(err, &apiErr) && apiErr.Code == "policy_denied" { … }

event, err := chainvara.VerifyWebhook(body,
    r.Header.Get("fos-signature"), webhookSecret, 0)

Java SDK

One file, no dependency (Java 11+, java.net.http): the same resources, retries with backoff, idempotency keys, typed errors, pagination, webhook and co-signer signatures. Put it in com/chainvara/ of your sources.

var cv = new Chainvara(System.getenv("CHAINVARA_API_KEY"));

var t = cv.transfers.create(Map.of("wallet_id", treasuryId,
    "asset", "USDC", "amount", "250", "destination", "@partner"), order.id());
try { … } catch (Chainvara.ChainvaraException e) {
    if (e.code.equals("policy_denied")) { … }
}

var event = Chainvara.verifyWebhook(rawBody,
    request.getHeader("fos-signature"), webhookSecret);

.NET SDK

One C# file, base library only (.NET 6+, HttpClient and System.Text.Json): async resources, retries with backoff, idempotency keys, typed errors, IAsyncEnumerable pagination, constant-time webhook and co-signer signatures.

var cv = new Chainvara(Environment.GetEnvironmentVariable("CHAINVARA_API_KEY")!);

var t = await cv.Transfers.CreateAsync(new { wallet_id = treasuryId,
    asset = "USDC", amount = "250", destination = "@partner" }, order.Id);
await foreach (var x in cv.Transfers.IterateAsync(Chainvara.Q(("tag", "payroll")))) { … }

var evt = Chainvara.VerifyWebhook(rawBody,
    Request.Headers["fos-signature"], webhookSecret);

Signed webhooks

Every event is POSTed to your https endpoint with a FOS-Signature: t=…,v1=… header: an HMAC-SHA256 of the timestamp and the raw body with your endpoint secret. Deliveries are retried with backoff and never sent to private addresses; every payload carries its seq to order and deduplicate. Send a signed test event from Developers, retry failures or replay a period after an outage, and rotate a secret without downtime: for 24 hours both secrets sign.

transfer.createdtransfer.approvedtransfer.rejectedtransfer.blockedtransfer.canceledtransfer.submittedtransfer.confirmedtransfer.failedtransfer.expiredtransfer.requires_reviewtransfer.sped_uptransfer.cancel_requestedwallet.createdtransaction.detecteddeposit.receiveddeposit.flaggeddeposit.releaseddeposit.reportedtravel_rule.receivedtravel_rule.acknowledgedembedded.backup_storedwallet.keys_refreshedembedded.backup_fetchedreconciliation.case_openedexecution.pausedaddress.addedaddress.revokedaddress.ownership_verifiedgovernance.requestedvault.frozenvault.unfrozenautomation.alertautomation.alert_clearedautomation.createdautomation.updatedautomation.deletedwallet.approval_detectednetwork.request.receivednetwork.request.sentnetwork.request.payingnetwork.request.declinednetwork.request.cancelednetwork.obligation.recordednetwork.obligation.confirmednetwork.obligation.disputednetwork.obligation.cancelednetwork.settlement.started
import { verifyWebhook } from "./chainvara.js";

app.post("/webhooks/chainvara", express.text({ type: "*/*" }), async (req, res) => {
  const event = await verifyWebhook(req.body, req.get("FOS-Signature"),
    process.env.CHAINVARA_WEBHOOK_SECRET);   // throws if forged or replayed
  if (event.type === "transfer.confirmed") await markPaid(event.data.id);
  res.sendStatus(200);
});

A tamper-evident audit trail

Every sign-in, approval, policy change, key and transfer is recorded with its actor, IP and details. The database refuses edits and deletions, numbers each entry without gaps and links it to the hash of the one before. Poll /audit?after= from Splunk, Datadog, Sentinel or Elastic, and keep the head hash: a history rewritten later no longer contains it.

let after = await state.get("chainvara_seq") ?? 0;
let lastHash = await state.get("chainvara_hash") ?? null;
const page = await fetch(`https://www.chainvara.com/api/v1/audit?after=${after}&limit=1000`,
  { headers: { authorization: `Bearer ${process.env.CHAINVARA_KEY}` } }).then((r) => r.json());
for (const e of page.data) {
  if (e.seq !== after + 1 || e.prev_hash !== lastHash) alert("audit chain broken");
  await siem.send(e);             // seq, action, actor_email, ip, detail, hash
  after = e.seq; lastHash = e.hash;
}
await state.set("chainvara_seq", after);
await state.set("chainvara_hash", lastHash);

Go further

Get your sandbox key

Free on public test networks, with the same API, policies and webhooks as production.