Guides

Integration Patterns

End-to-end recipe for issuing a compliance-gated token

View as Markdown
GUIDES · INTEGRATION PATTERNS

This guide walks you through a complete partner-issuer integration from scratch. You will onboard an organization, attest investor wallets, define a compliance policy, deploy a gated token, and subscribe to lifecycle events. Each step is a thin summary with a single SDK snippet — follow the linked building-block guide for the full walkthrough.

The worked example uses a fictional beekeeping company, HoneyB, that tokenizes honey production shares under Regulation D.

Prerequisites

Before starting, make sure you have:

End-to-end flow

 1. Onboard org         Create org, API keys, enable chains, register as issuer
        |
 2. Attest wallets      Org-initiated attestation for each investor
        |
 3. Create asset        Define the tokenized asset (symbol, type, supply)
        |
 4. Define policy       Attach compliance rules, then deploy on-chain
        |
 5. Subscribe events    Wire webhooks for attestation + compliance channels

1. Onboard the issuer organization

Create the organization, generate an API key, enable your target chains, and register as an issuer. This gives you the orgId and credentials every subsequent call requires.

onboard.ts
1import { SignumClient } from "@signum-tech/sdk";
2
3const signum = new SignumClient({ apiKey: process.env.SIGNUM_API_KEY });
4
5const org = await signum.orgs.create({
6  name: "HoneyB",
7  email: "ops@honeyb.com",
8  org_type: "organization",
9});

After creating the org, generate an API key, enable chains, and register as an issuer. See Onboard an Organization for the full step-by-step.

Keep your org on testnet until you have validated the full integration end-to-end. Switch to mainnet only when ready for production.

2. Attest investor wallets

Before investors can hold your token, their wallets need an on-chain attestation. Use the org-initiated path to attest members whose identity you have already verified.

attest-investor.ts
1const result = await signum.orgs.members.attest(org.id, investorUserId, {
2  kycLevel: 2,
3  countryCode: "US",
4  reason: "Accredited investor verification complete",
5});

The API returns 202 Accepted — the attestation is queued for on-chain settlement. See Attest a User for the full walkthrough including the self-service path and KYC initiation.

3. Create the tokenized asset

Create the asset record that represents your token. This produces the assetId you will reference when attaching a compliance policy and deploying on-chain.

create-asset.ts
1const asset = await signum.orgs.assets.create(org.id, {
2  name: "HoneyB Production Shares",
3  symbol: "HNYB",
4  asset_type: "equity",
5  regulation_type: "reg_d",
6  total_supply: 1000000,
7  decimals: 18,
8});

The API returns 202 Accepted. See Deploy a Gated Asset for the full asset lifecycle including token allocation and cross-chain bridging.

4. Define the compliance policy and deploy

Attach the transfer rules that the smart contract will enforce, then deploy the asset as an OFT (Omnichain Fungible Token) on the target chain. This example configures Regulation D with accredited-investor requirements and a one-year lockup.

policy-and-deploy.ts
1await signum.orgs.assets.compliancePolicy.set(org.id, asset.assetId, {
2  regulation_type: "reg_d",
3  min_kyc_level: 2,
4  accredited_investor_required: true,
5  blocked_countries: ["IRN", "PRK", "CUB"],
6  max_holders: 2000,
7  lockup_period_days: 365,
8  chain_eid: 30101,
9});
10
11await signum.orgs.assets.deploy(org.id, asset.assetId, {
12  chain_eid: 30101,
13});

Both calls return 202 Accepted. Deployment typically takes 30-120 seconds depending on chain congestion. See Define a Compliance Policy for the full field reference and Deploy a Gated Asset for polling and deployment status.

The compliance policy must be attached before deployment. You can attach it immediately after asset creation (step 3) or inline during the create call.

5. Subscribe to lifecycle events

Wire webhook endpoints to receive real-time notifications when attestations settle and compliance checks complete. This replaces polling in production integrations.

subscribe.ts
1// Configure webhook endpoints in the Clossir dashboard at:
2// https://app.dev.clossir.com/ → Organization Settings → Webhooks
3//
4// Key channels to subscribe to:
5// - signum.attestation.created
6// - signum.attestation.revoked
7// - signum.compliance.check_completed
8// - signum.compliance.rule_synced

See Subscribe to Webhooks for the full handler implementation, payload schemas, tracing headers, and failure handling.

What you built

You now have a complete issuer integration:

  1. An organization registered as an issuer with API keys and enabled chains
  2. Investor wallets attested on-chain with KYC verification
  3. A tokenized asset representing your security
  4. A compliance policy enforcing Regulation D, deployed as a gated OFT on-chain
  5. Webhook subscriptions delivering real-time lifecycle events

Every token transfer is automatically checked against your compliance policy — blocked countries, KYC levels, accreditation status, holder limits, and lockup periods are all enforced on-chain.

Reference

Next steps