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.

15. RWA Securities Register

Registers a traditional financial asset / private placement security under BitGo RWA's SEC-registered Transfer Agent rails.

Request Body:

{
  "issuerName": "Meridian Real Estate Fund III",
  "securityType": "LP_INTEREST",
  "regulationType": "REG_D_506C",
  "totalShares": 10000000,
  "parValue": 10.00,
  "jurisdiction": "US_DE"
}

Response Body:

{
  "status": "success",
  "securityId": "sec_b3g0rwa1",
  "issuerName": "Meridian Real Estate Fund III",
  "securityType": "LP_INTEREST",
  "regulationType": "REG_D_506C",
  "totalShares": 10000000,
  "parValue": 10.0,
  "jurisdiction": "US_DE",
  "createdAt": "2026-07-05T18:45:00.000Z",
  "securityStatus": "ACTIVE",
  "cusip": "CUSIP-483921",
  "isin": "US4839210020",
  "transferAgent": "BitGo Transfer Agent Services N.A."
}

16. RWA Securities Transfer

Initiates a compliant, ownership-verified security transfer between accounts (e.g. primary issuance or secondary trading).

Request Body:

{
  "securityId": "sec_b3g0rwa1",
  "fromHolder": "issuer_treasury",
  "toHolder": "investor_7b2e4c8f",
  "shares": 50000,
  "transferType": "PRIMARY_ISSUANCE",
  "accreditationVerified": true
}

Response Body:

{
  "status": "success",
  "transactionId": "tx_trsf8f32a2",
  "securityId": "sec_b3g0rwa1",
  "fromHolder": "issuer_treasury",
  "toHolder": "investor_7b2e4c8f",
  "shares": 50000,
  "transferType": "PRIMARY_ISSUANCE",
  "state": "confirmed",
  "processedAt": "2026-07-05T18:45:05.000Z",
  "accruedDividends": 0.0,
  "feeBps": 15,
  "custodian": "BitGo Bank & Trust N.A."
}

17. RWA Offerings Create

Provisions a new capital raise structure, defining terms, target amounts, limits, and creating the escrow holding rails.

Request Body:

{
  "issuer": "Meridian Capital Partners",
  "offeringName": "Fund III Capital Raise",
  "regulationType": "REG_D_506C",
  "targetRaise": 50000000,
  "minimumInvestment": 100000,
  "maximumInvestment": 5000000,
  "acceptedCurrencies": ["USD", "USDC"],
  "escrowRequired": true
}

Response Body:

{
  "status": "success",
  "offeringId": "off_cf92k1ad",
  "offeringName": "Fund III Capital Raise",
  "issuer": "Meridian Capital Partners",
  "regulationType": "REG_D_506C",
  "targetRaise": 50000000,
  "minimumInvestment": 100000,
  "maximumInvestment": 5000000,
  "acceptedCurrencies": ["USD", "USDC"],
  "escrowRequired": true,
  "escrowAccountId": "esc_ba921fcd3",
  "state": "OPEN",
  "createdAt": "2026-07-05T18:45:10.000Z",
  "escrowBank": "BitGo Bank & Trust N.A."
}

18. RWA Offerings Subscribe

Processes an investor subscription request, verifying compliance rules, signatures, and initiating wire/USDC escrow holds.

Request Body:

{
  "offeringId": "off_cf92k1ad",
  "investorId": "inv_3c8d2e4f",
  "amount": 250000,
  "currency": "USD",
  "accreditationStatus": "VERIFIED",
  "subscriptionAgreementSigned": true,
  "fundingMethod": "WIRE"
}

Response Body:

{
  "status": "success",
  "subscriptionId": "sub_s82fcd8f2a",
  "offeringId": "off_cf92k1ad",
  "investorId": "inv_3c8d2e4f",
  "amount": 250000,
  "currency": "USD",
  "accreditationStatus": "VERIFIED",
  "subscriptionAgreementSigned": true,
  "fundingMethod": "WIRE",
  "state": "approved",
  "escrowDepositStatus": "PENDING",
  "webhookEventDispatched": "rwa.subscription.created"
}