Onboarding

Entity onboarding, KYC/KYB verification, and wallet registration.

Overview

Before a counterparty can transact on a compliance-enabled protocol, they must complete identity verification (KYC for individuals, KYB for businesses). The onboarding flow:

Create an entity with legal information and wallet addresses
Automated compliance checks run (KYC/KYB, AML, sanctions, UBO)
Once approved, the compliance oracle is updated on-chain
The entity can now transact through compliant protocols

Create an Entity

curl -X POST https://api.overvoid.io/v1/onboarding/entities \
  -H "Authorization: Bearer cusd_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "legal_name": "Acme Corp",
    "jurisdiction": "US-DE",
    "entity_type": "corporation",
    "registration_number": "1234567",
    "wallets": [
      {
        "chain_id": 11155111,
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      },
      {
        "chain_id": 421614,
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    ]
  }'

The same wallet address can be registered on multiple chains. Each chain is tracked independently for compliance.

Compliance Checks

After entity creation, automated checks are dispatched:

Check	What It Verifies
KYB	Business registration, legal name, address
UBO	Ultimate beneficial ownership (25%+ holders)
AML	Anti-money laundering screening
Sanctions	Global sanctions list screening

Check progress with:

curl https://api.overvoid.io/v1/onboarding/entities/{entity_id}/compliance-checks \
  -H "Authorization: Bearer cusd_test_YOUR_KEY"

Entity Status

Status	Meaning
`pending`	Created, awaiting compliance checks
`active`	Approved, can transact through compliant protocols
`suspended`	Temporarily blocked (pending review)
`rejected`	KYB failed or prohibited jurisdiction

Add Wallets Later

curl -X POST https://api.overvoid.io/v1/onboarding/entities/{entity_id}/wallets \
  -H "Authorization: Bearer cusd_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain_id": 84532,
    "address": "0x1234567890abcdef1234567890abcdef12345678"
  }'

New wallets inherit the entity's compliance status and are immediately updated in the on-chain oracle.

Compliance Expiry

Compliance checks have expiry dates. The oracle stores per-check expiry timestamps. When a check expires, the wallet can no longer transact until re-verification completes. Monitor expiry via:

curl https://api.overvoid.io/v1/compliance/status/{entity_id} \
  -H "Authorization: Bearer cusd_test_YOUR_KEY"

Subscribe to compliance.status_changed and account.kyb_expired webhooks for proactive notifications.