⚠️ 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-Keywhen 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 evidencecontracts:write: Create and edit drafts, send them for signature, and everything the narrower write scopes allowcontracts:sign: Request signing and approval messages and submit signatures and approvalscontracts:activate: Activate signed contracts and request evaluationevidence:read: Download agreements and evidence bundleswebhooks:manage: Create, list, test and delete webhook subscriptions (creating one also needs contracts:read)
Lifecycle
- Pick a template (
GET /templates) or write a dc/2 draft; check it withPOST /dsl/validateand/dsl/simulate. - Create it (
POST /contracts) and send it for signatures (POST /contracts/{id}/finalize). - Each party gets a signing challenge (
POST …/signing-request), signs it in their own wallet, and submits it (POST …/signatures). - Activate (
POST …/activate). Contracts evaluates it on confirmed blocks. - Follow it:
GET …/state(each condition's result and who enforces it),…/events,…/evaluations,…/attempts, or a webhook. - Verify it independently:
GET …/evidenceorGET /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.