> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.clossir.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.clossir.com/_mcp/server.

# Integration Patterns

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:

* A Clossir account ([app.dev.clossir.com](https://app.dev.clossir.com/))
* Node.js 18+ or Bun
* `@signum-tech/sdk` installed (`npm install @signum-tech/sdk`)
* Familiarity with each building-block guide:
  * [Onboard an Organization](/guides/onboard-org)
  * [Attest a User](/guides/attest-user)
  * [Define a Compliance Policy](/guides/define-policy)
  * [Deploy a Gated Asset](/guides/deploy-asset)
  * [Subscribe to Webhooks](/guides/subscribe-webhooks)

## 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.

```ts title="onboard.ts"
import { SignumClient } from "@signum-tech/sdk";

const signum = new SignumClient({ apiKey: process.env.SIGNUM_API_KEY });

const org = await signum.orgs.create({
  name: "HoneyB",
  email: "ops@honeyb.com",
  org_type: "organization",
});
```

After creating the org, generate an API key, enable chains, and register as an issuer.
See [Onboard an Organization](/guides/onboard-org) 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.

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

The API returns `202 Accepted` — the attestation is queued for on-chain settlement.
See [Attest a User](/guides/attest-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.

```ts title="create-asset.ts"
const asset = await signum.orgs.assets.create(org.id, {
  name: "HoneyB Production Shares",
  symbol: "HNYB",
  asset_type: "equity",
  regulation_type: "reg_d",
  total_supply: 1000000,
  decimals: 18,
});
```

The API returns `202 Accepted`. See [Deploy a Gated Asset](/guides/deploy-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.

```ts title="policy-and-deploy.ts"
await signum.orgs.assets.compliancePolicy.set(org.id, asset.assetId, {
  regulation_type: "reg_d",
  min_kyc_level: 2,
  accredited_investor_required: true,
  blocked_countries: ["IRN", "PRK", "CUB"],
  max_holders: 2000,
  lockup_period_days: 365,
  chain_eid: 30101,
});

await signum.orgs.assets.deploy(org.id, asset.assetId, {
  chain_eid: 30101,
});
```

Both calls return `202 Accepted`. Deployment typically takes 30-120 seconds depending on
chain congestion. See [Define a Compliance Policy](/guides/define-policy) for the full
field reference and [Deploy a Gated Asset](/guides/deploy-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.

```ts title="subscribe.ts"
// Configure webhook endpoints in the Clossir dashboard at:
// https://app.dev.clossir.com/ → Organization Settings → Webhooks
//
// Key channels to subscribe to:
// - signum.attestation.created
// - signum.attestation.revoked
// - signum.compliance.check_completed
// - signum.compliance.rule_synced
```

See [Subscribe to Webhooks](/guides/subscribe-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

* [API Reference](/api/overview) — the full operation catalog and webhook payload schemas
* [Concepts](/getting-started/concepts) — the Clossir data model
* [Authentication](/getting-started/authentication) — scopes, keys, and error handling

## Next steps

* [Async Operations](/getting-started/sdk/async-operations) — polling and webhook correlation patterns
* [Error Handling](/getting-started/sdk/error-handling) — structured error responses and retry guidance
* [React Integration](/getting-started/sdk/react) — embed the attestation flow in your frontend