Skip to content
DigiStamp Contracts, home

⚠️ NOTICE: Deployment Testing in Progress We have recently deployed a major platform update and are currently performing post-deployment testing and validation. Some features may be unavailable or behave unexpectedly. Thank you for your patience as we work to ensure everything is functioning correctly.

Developers

Build on Contracts: a versioned REST API, signed webhooks and a TypeScript SDK. Everything here works against your own local instance, with no access to DigiStamp's databases or credentials.

The API

Base path
/api/contracts/v1
Specification
OpenAPI 3.1 (JSON)
Authentication
An API key in Authorization: Bearer dck_…, created under Settings → API keys after signing in with Digi-ID. Keys act as your account, never with admin powers.
Public endpoints
Templates, DSL validation and simulation, the explorer and verification need no key.
Pagination
Lists return nextCursor; pass it back as ?cursor=. Cursors are opaque and stable while items are added.
Rate limits
Per key per minute (and per IP for public endpoints). A 429 carries Retry-After.
Idempotency
Send Idempotency-Key when creating a contract; a retry returns the same contract.
Errors
{ "error": { "code", "message", "issues", "requestId" } }

Scopes

  • contracts:read: Read contracts you own or are a party to, their state, history and evidence
  • contracts:write: Create and edit drafts, send them for signature, and everything the narrower write scopes allow
  • contracts:sign: Request signing and approval messages and submit signatures and approvals
  • contracts:activate: Activate signed contracts and request evaluation
  • evidence:read: Download agreements and evidence bundles
  • webhooks:manage: Create, list, test and delete webhook subscriptions (creating one also needs contracts:read)

Lifecycle

  1. Pick a template (GET /templates) or write a dc/2 draft; check it with POST /dsl/validate and /dsl/simulate.
  2. Create it (POST /contracts) and send it for signatures (POST /contracts/{id}/finalize).
  3. Each party gets a signing challenge (POST …/signing-request), signs it in their own wallet, and submits it (POST …/signatures).
  4. Activate (POST …/activate). Contracts evaluates it on confirmed blocks.
  5. Follow it: GET …/state (each condition's result and who enforces it), …/events, …/evaluations, …/attempts, or a webhook.
  6. Verify it independently: GET …/evidence or GET /verify/{hash}/evidence, checked with the SDK or the standalone verifier.

TypeScript SDK

import { DigiContractClient, assertSigningMessage, signMessage } from "@digistamp/digicontract-sdk";

const client = new DigiContractClient({ baseUrl: "https://contracts.digistamp.co", apiKey: process.env.DIGICONTRACT_API_KEY });
const { templates } = await client.templates.list({ q: "approval" });
const state = await client.contracts.state(contractId);
for (const c of state.conditions) console.log(c.key, c.result, c.layerLabel);

The SDK lives in packages/contracts-sdk of the DigiStamp platform repository. Create an API key under API keys.

Webhooks

Subscribe to contract events (POST /webhooks). Each delivery is an HTTPS POST signed with HMAC-SHA256 (DigiContract-Signature: t=…,v1=…), carries a delivery id for de-duplication, and is retried with backoff for about a day. Reject timestamps older than five minutes; the SDK's verifyWebhook does all of this.

Trust boundaries

Every condition says who enforces it: DigiByte consensus, DigiAsset indexers, Contracts' application, or cryptography anyone can check. API responses carry the same labels (layer, layerLabel). The API reports Contracts' view; the evidence bundle lets you check it without trusting Contracts.