Developer API Reference

Overview

The Unykorn B2B API gateway acts as a secure custody middleware proxying institutional credit, wallets, and sweep pipelines to local BitGo Express instances and BitGo Trust N.A. APIs.

Relational Postgres Idempotency Ledger:

-- Table used to track webhook notifications and prevent duplicate executions (Idempotency)
CREATE TABLE webhook_notifications (
  id              SERIAL PRIMARY KEY,
  notification_id VARCHAR(255) UNIQUE NOT NULL,  -- BitGo's notification ID
  type            VARCHAR(100) NOT NULL,          -- transfer, kycState, etc.
  coin            VARCHAR(50),
  wallet_id       VARCHAR(255),
  payload         JSONB NOT NULL,
  verified        BOOLEAN DEFAULT FALSE,
  created_at      TIMESTAMP DEFAULT NOW()
);

-- Table used to track KYC status changes from Sumsub integrations
CREATE TABLE client_kyc_status (
  id              SERIAL PRIMARY KEY,
  enterprise_id   VARCHAR(255) NOT NULL,
  user_id         VARCHAR(255),
  kyc_state       VARCHAR(100) NOT NULL,
  created_at      TIMESTAMP DEFAULT NOW()
);

-- Table used to track sweep transactions
CREATE TABLE transaction_sweeps (
  id              SERIAL PRIMARY KEY,
  transfer_id     VARCHAR(255) UNIQUE NOT NULL,
  wallet_id       VARCHAR(255) NOT NULL,
  coin            VARCHAR(50) NOT NULL,
  amount          NUMERIC NOT NULL,
  state           VARCHAR(100) NOT NULL,
  txid            VARCHAR(255),
  created_at      TIMESTAMP DEFAULT NOW()
);

1. Health Diagnostics

Queries dual-dependency connectivity to verify that the local Express container is active and authorization credentials can ping the BitGo production network successfully.

Response Example (Healthy - 200 OK):

{
  "server": "ok",
  "express": "service is ok!",
  "api": "authenticated",
  "environment": "BitGo Testnet",
  "timestamp": "2026-07-05T15:21:44.201Z"
}

Response Example (Degraded - 503 Service Unavailable):

{
  "server": "ok",
  "express": "unreachable",
  "expressError": "connect ECONNREFUSED 127.0.0.1:4000",
  "api": "unreachable",
  "apiError": "error_401",
  "timestamp": "2026-07-05T15:22:10.512Z"
}

2. Provision Child Enterprise

Initiates onboarding under your organizational umbrella to allocate a child enterprise boundary for institutional clients.

Request Body:

{
  "email": "treasury@apex.com",
  "accountType": "business"
}

Response Example (200 OK):

{
  "id": "ent_prod_69a0b54edd793f289161ec0c50cee070",
  "name": "Apex Mining Corp (CaaS)",
  "organization": "org_unykorn_99834282ba01",
  "status": "active"
}

3. Provision Go Account Wallet

Generates an institutional trading/custody wallet container and automatically binds transfer webhooks to it.

Request Body:

{
  "childEnterpriseId": "ent_prod_69a0b54edd793f289161ec0c50cee070",
  "label": "Apex Custody Vault"
}

Response Example (200 OK):

{
  "id": "0xd6d5132e3a7f379acfe4bcd0130cc9e77884692a",
  "label": "Apex Custody Vault",
  "coin": "tbase",
  "enterprise": "ent_prod_69a0b54edd793f289161ec0c50cee070",
  "status": "fulfilled",
  "createdAt": "2026-07-05T15:21:44.205Z"
}

4. Query Custody Wallet Balance

Fetches verified available balances and deposit parameters for any asset coin type index.

Response Example (200 OK):

{
  "id": "0xd6d5132e3a7f379acfe4bcd0130cc9e77884692a",
  "coin": "ofc",
  "balance": "154000000",
  "confirmedBalance": "154000000",
  "spendableBalanceString": "154000000",
  "receiveAddress": {
    "address": "tb1q7w6xmjmdfjkwmsdn73h07gsw778h9jsw7w8s9s"
  }
}

5. Configure LTV Limit Rule

Registers maximum limits on loan drawdowns. Both client-side and server-side middleware enforces a strict 35% cap.

Request Body:

{
  "walletId": "0xd6d5132e3a7f379acfe4bcd0130cc9e77884692a",
  "collateralValueUSD": 100000,
  "currentLoanAmountUSD": 30000
}

Response Example (LTV Exceeded - 400 Bad Request):

{
  "error": "LTV_EXCEEDED",
  "message": "Transaction rejected by server-side LTV policy. Requested loan of $40000 against $100000 collateral yields 40.0% LTV, exceeding the 35% maximum cap.",
  "computed": {
    "ltv": "40.0",
    "max": 35
  }
}

6. Execute Custody Spend

Transfers assets to external addresses using cryptographic signatures computed by the local BitGo Express. Pre-flight checks prevent integer overflow on large base-unit decimals.

Request Body:

{
  "walletId": "0xd6d5132e3a7f379acfe4bcd0130cc9e77884692a",
  "coin": "tbtc4",
  "address": "tb1q7w6xmjmdfjkwmsdn73h07gsw778h9jsw7w8s9s",
  "amount": "10000",
  "walletPassphrase": "your_wallet_passphrase"
}

Response Example (200 OK):

{
  "txid": "tx_sim_wj6ubo382kds",
  "message": "Simulated spend of 10000 tbtc4 to tb1q7w6xmjmdfjkwmsdn73h07gsw778h9jsw7w8s9s completed successfully."
}

7. Webhook Receiver Endpoint

Accepts raw payloads sent by BitGo's webhook dispatch engines. HMAC signatures are computed over raw request bodies to block tampered signals.

Required Request Headers:

Response Status Codes:

8. Register Enterprise Webhook

Instructs BitGo to forward specific events (transfers, kyc state updates, manual pending approvals) to your public receiver URL.

Request Body:

{
  "type": "transfer",
  "url": "https://api.unykorn.ai/api/bitgo/webhook/receive"
}

9. Webhook Health Monitor

Lists active webhooks and flags if any notifications have been suspended due to transport delivery failure limits (max 100 failures/week).

Response Example (200 OK):

{
  "total": 3,
  "active": 3,
  "suspended": 0,
  "webhooks": [
    { "type": "transfer", "state": "active", "url": "https://api.unykorn.ai/api/bitgo/webhook/receive" },
    { "type": "enterpriseKycState", "state": "active", "url": "https://api.unykorn.ai/api/bitgo/webhook/receive" }
  ]
}

10. Access Token Lifecycle

Fetches a new BitGo access token and handles lifecycle rotation via BitGo's login endpoint.

11. Receive Address Generation

Generates a dedicated receive address for a specific wallet, preventing address reuse, and logs it in the internal database.

12. Transaction History

Fetches transfer history for a given wallet using BigInt-safe value serialization and cursor-based pagination.

Retrieve a specific transfer:

13. Pending Approvals

Handle transactions blocked by velocity limit policies.

Approve or reject a pending transaction. Note: Approvers cannot approve their own transactions. Requires x-approver-token header.

14. Webhook Reconciliation

Self-healing mechanism to fetch all missed transfers from BitGo since the last successful webhook event and insert them into the database.