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": "[email protected]",
  "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"
}

19. Advanced Wallets Setup (AWM & MBE)

Configure on-premise user key protection using AWM (Advanced Wallet Manager) and Master BitGo Express (MBE) with mutual TLS (mTLS) client verification.

19.1 MBE Health Check

Response Body:

{
  "status": "master express server is ok!",
  "timestamp": "2026-07-05T22:59:54.738Z"
}

19.2 AWM Inter-Service Communication

Response Body:

{
  "status": "Successfully pinged advanced wallet manager",
  "awmResponse": {
    "status": "advanced wallet manager server is ok!",
    "timestamp": "2026-07-05T23:00:57.970Z"
  }
}

19.3 Production Docker Compose Configuration Template

Deploy both servers in Docker using secure internal-bridge routing limits:

version: '3.8'

services:
  advanced-wallet-manager:
    image: node:22-alpine
    container_name: advanced-wallet-manager
    networks:
      - my-internal-network
    environment:
      - APP_MODE=advanced-wallet-manager
      - ADVANCED_WALLET_MANAGER_PORT=3080
      - TLS_MODE=mtls
      - SERVER_TLS_KEY_PATH=/app/certs/awm-server-key.pem
      - SERVER_TLS_CERT_PATH=/app/certs/awm-server-cert.pem
      - MTLS_ALLOWED_CLIENT_FINGERPRINTS=sha256:D1:E9:5A:F2...
    volumes:
      - ./certs:/app/certs:ro

  master-bitgo-express:
    image: node:22-alpine
    container_name: master-bitgo-express
    ports:
      - "3081:3081"
    networks:
      - my-internal-network
      - my-public-network
    environment:
      - APP_MODE=master-express
      - MASTER_EXPRESS_PORT=3081
      - ADVANCED_WALLET_MANAGER_URL=https://advanced-wallet-manager:3080
      - TLS_MODE=mtls
      - SERVER_TLS_KEY_PATH=/app/certs/mbe-server-key.pem
      - SERVER_TLS_CERT_PATH=/app/certs/mbe-server-cert.pem
    volumes:
      - ./certs:/app/certs:ro

networks:
  my-internal-network:
    driver: bridge
    internal: true
  my-public-network:
    driver: bridge

20. Bitcoin Lightning Network (Custody & Go Lightning)

Configure off-chain Bitcoin payments using Lightning wallets, enabling instant settlements, microtransactions, and Go Account integration.

20.1 Create Lightning Invoice

Generates a new off-chain Bitcoin Lightning network invoice for receiving payments.

Request Body:

{
  "walletId": "69a0b54edd793f289161ec0c50cee070",
  "amountSats": 50000,
  "memo": "Unykorn Invoice Sweep #889"
}

Response Body:

{
  "status": "success",
  "invoice": "lnbc500u1p3x0m8y7g...",
  "paymentHash": "hash_82afcd77e23b18d2",
  "amountSats": 50000,
  "memo": "Unykorn Invoice Sweep #889",
  "expiresAt": "2026-07-05T23:59:54.738Z"
}

20.2 Pay Lightning Invoice

Routes and settles an off-chain Bitcoin Lightning invoice. Custody wallets require a valid User Authentication Key signature.

Request Body:

{
  "walletId": "69a0b54edd793f289161ec0c50cee070",
  "invoice": "lnbc500u1p3x0m8y7g...",
  "userAuthSignature": "sig_558aef22d3cd47f9c882a7f050ce9a008c2d1b77"
}

Response Body:

{
  "status": "settled",
  "paymentHash": "hash_12cba82e02d8471e",
  "feeMsat": 1000,
  "settledAt": "2026-07-05T19:07:30.000Z",
  "message": "Lightning payment routed and settled successfully off-chain."
}

20.3 Withdraw On-chain from Lightning Wallet

Settle off-chain funds on-chain by executing a withdrawal to a standard base-layer Bitcoin address.

Request Body:

{
  "walletId": "69a0b54edd793f289161ec0c50cee070",
  "amountSats": 80000,
  "address": "tb1q7w6xmjmdfjkwmsdn73h07gsw778h9jsw7w8s9s"
}

Response Body:

{
  "status": "broadcasted",
  "txid": "tx_28dfca182e0db7e128dfca182e0db7e1",
  "amountSats": 80000,
  "destination": "tb1q7w6xmjmdfjkwmsdn73h07gsw778h9jsw7w8s9s",
  "feeSats": 250,
  "broadcastedAt": "2026-07-05T19:07:30.000Z"
}

21. Stablecoin Issuance & Redemption (Minting & Burning)

Configure fiat-backed stablecoin minting and burning services linked to Go Account fiat cash reserves, governed by customizable enterprise policies.

21.1 Mint Stablecoins

Mints stablecoin tokens (e.g., USD1) backed by fiat funds deposited in a Go Account.

Request Body:

{
  "walletId": "69a0b54edd793f289161ec0c50cee070",
  "amountUSD": 1000000,
  "token": "USD1",
  "destinationAddress": "0x8aced25DC8530FDaf0f86D53a0A1E02AAfA7Ac7A"
}

Response Body:

{
  "status": "pending_approval",
  "mintTxId": "tx_82afcd77e23b18d2",
  "amountMinted": 1000000,
  "token": "USD1",
  "destinationAddress": "0x8aced25DC8530FDaf0f86D53a0A1E02AAfA7Ac7A",
  "policyCheck": "Awaiting 2FA signature matching policy rules. Auto-locks within 48h.",
  "requestedAt": "2026-07-05T23:59:54.738Z"
}

21.2 Burn Stablecoins

Burns stablecoin tokens to redeem them for fiat currency deposited back to a Go Account.

Request Body:

{
  "walletId": "69a0b54edd793f289161ec0c50cee070",
  "amountToken": 500000,
  "token": "USD1"
}

Response Body:

{
  "status": "completed",
  "burnTxId": "tx_12cba82e02d8471e",
  "amountBurned": 500000,
  "fiatRedeemedUSD": 500000,
  "token": "USD1",
  "burnedAt": "2026-07-05T19:07:30.000Z",
  "message": "Stablecoin tokens burnt. Fiat funds credited back to Go Account balance."
}

21.3 List Supported Stablecoins

Returns a list of all fiat-backed stablecoins supported under the Go Account minting/burning system.

Response Body:

[
  {
    "token": "USD1",
    "name": "USD1",
    "supportedChains": ["ETH", "BSC", "TRX", "SOL", "APT", "TEMPO"],
    "issuer": "BitGo Trust Company N.A.",
    "peggedCurrency": "USD"
  },
  {
    "token": "SOFID",
    "name": "SoFiUSD",
    "supportedChains": ["ETH", "SOL"],
    "issuer": "SoFi Digital Assets LLC",
    "peggedCurrency": "USD"
  },
  {
    "token": "USDC",
    "name": "USD Coin (CCTP V2)",
    "supportedChains": ["ETH", "SOL", "BASE", "ARB", "OP", "POLY"],
    "issuer": "Circle Internet Financial",
    "peggedCurrency": "USD"
  },
  {
    "token": "RLUSD",
    "name": "Ripple USD",
    "supportedChains": ["XRPL", "ETH"],
    "issuer": "Ripple Labs Inc.",
    "peggedCurrency": "USD"
  },
  {
    "token": "USDT0",
    "name": "LayerZero USD Token (OFT v2)",
    "supportedChains": ["ETH", "BASE", "SOL", "ARB"],
    "issuer": "LayerZero & Tether",
    "peggedCurrency": "USD"
  }
]

21.4 Stablecoin Rail Migration (Circle CCTP V1 to V2)

Pursuant to Manager Written Resolution III, Unykorn requires all active enterprise client accounts to migrate all USDC integrations from Circle CCTP V1 to CCTP V2 before the sunset date of July 31, 2026. Integrations failing to migrate will experience transaction routing deprecation.

22. Custody Wallets & Multi-Party Computation (MPC)

BitGo secures digital assets utilizing a robust Multi-Party Computation (MPC) and multi-signature key structure. Private key shards are distributed among independent systems, eliminating any single-point-of-failure vulnerabilities.

22.1 The 2-of-3 Multi-Signature & Threshold Key Model

For standard custody wallets, BitGo employs three keys distributed among independent parties:

• User Key (Key 1): Held directly by the operator (Unykorn). Encrypted client-side using user passwords, ensuring self-custody or authorized custody initiation.
• Backup Key (Key 2): Held offline by an independent third-party trustee (e.g., Coincover). Used solely for disaster recovery if the user key is lost.
• BitGo Key (Key 3): Maintained in BitGo's secure Hardware Security Modules (HSMs). Co-signs transactions only when all enterprise security rules, policy constraints (e.g. 35% LTV limit), and 2FA/OTP approvals are validated.

22.2 Multi-Party Computation (MPC) TSS Keysets

For advanced chains (like Solana, Cardano, and near-future networks), BitGo uses Threshold Signature Schemes (TSS) where key shares collaboratively generate signatures off-chain. Individual key shares are never reconstructed in single locations, maintaining total cryptographic separation.

22.3 Key Verification Probe

Developers can test connection and sign payloads with local BitGo Express instances to verify that HSM key paths are accessible.

Response Body:

{
  "status": "active",
  "hsmConnection": "verified",
  "mbeVersion": "22.8.2",
  "clientFingerprint": "sha256:D1:E9:5A:F2..."
}

23. Webhook Event Notifications & Signature Verification

Real-time updates for transactions, wallet changes, and policy approvals are dispatched as HTTP POST webhooks to operator receivers. Operators must verify incoming webhook signatures to ensure authenticity.

23.1 Webhook Delivery Payload Format

Incoming POST request body schema for transfer webhooks:

{
  "event": "transfer",
  "walletId": "69a0b54edd793f289161ec0c50cee070",
  "transferId": "tx_28dfca182e0db7e128dfca182e0db7e1",
  "coin": "ofctusd",
  "amount": 25000000,
  "state": "confirmed",
  "timestamp": "2026-07-05T19:07:30.000Z"
}

23.2 Verifying the BitGo Signature

Every webhook contains a header named x-bitgo-signature. The signature is a SHA-256 HMAC generated over the raw payload string using the webhook's registered secret.

Example Express middleware for verification:

const crypto = require('crypto');

function verifyBitGoWebhook(req, res, next) {
  const signature = req.headers['x-bitgo-signature'];
  const webhookSecret = process.env.BITGO_WEBHOOK_SECRET;

  if (!signature) {
    return res.status(401).send('Missing BitGo signature header');
  }

  const hmac = crypto.createHmac('sha256', webhookSecret);
  hmac.update(JSON.stringify(req.body));
  const expectedSignature = hmac.digest('hex');

  if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
    return next(); // Webhook verified
  }

  return res.status(403).send('Invalid signature');
}

24. Policy & Approval Engine

Configure enterprise-grade security rules to govern spend and administrative operations. All transfers are subject to automated evaluation.

24.1 Policy Rules & Spending Limits

Enterprises define policies such as maximum transaction value limits, allowed destination whitelists, and required co-signers (such as a 3-of-5 approval board). For Unykorn, the 35% LTV margin limit acts as a pre-flight policy block.

24.2 48-Hour Change Lock

To prevent malicious admin takeovers, BitGo locks all policies 48 hours after creation. Modifying existing policies requires submitting a request to [email protected] and undergoing out-of-band video ID verification.

24.3 Approvals API

Transactions exceeding policy thresholds trigger a pendingApproval status, requiring 2FA signature confirmation from authorized personnel.

Response Body:

{
  "status": "frozen",
  "enterpriseId": "69a0b54edd793f289161ec0c50cee070",
  "policyLocked": true,
  "action": "All transaction execution frozen until out-of-band video verification is complete."
}

25. Go Account Deep Dive (OFC Wallets)

Go Accounts are off-chain custodial clearing accounts managed by BitGo Trust Company N.A. They allow instant transfers across chains and fiat assets without waiting for base-layer blockchain confirmation times.

25.1 Satoshi-Precision Operations

Unlike other platforms using millisatoshi scales, BitGo's internal ledger operations for Go Accounts run on exact Satoshi precision. This avoids fractional rounding mismatch errors during high-frequency swaps or sweep operations.

25.2 Settlement Routing

Asset balances inside Go Accounts represent actual audited claims on segregated fiat and crypto reserves held in trust. Instantly route balances off-chain or convert them to native coins on base layers (e.g. BTC, ETH) via standard on-chain withdrawals.

26. Transaction Lifecycle & States

BitGo transactions transition through a series of deterministic states from creation to finality. Developers should monitor webhook event state fields:

27. Trading & OTC Services (BitGo Prime)

BitGo Prime offers institutional liquidity and OTC trading services directly integrated with secure custody wallets. Swap digital assets and convert crypto to fiat currencies with zero slippage or counterparty risks.

27.1 Request For Quote (RFQ)

Request live, guaranteed bid/ask pricing for asset pairs. RFQs remain valid for exactly 10 seconds before expiration.

27.2 Spot Conversion Execution

Upon accepting an RFQ, trade settlement executes atomically off-chain between custody vault ledgers. Settled fiat funds are instantly credited to the designated Go Account balance.

28. Settlement & Reconciliation

Audit and balance transaction data across blockchain nodes, custody ledgers, and off-chain clearing repositories.

28.1 RWA Ledger Matching

Real-World Asset (RWA) subscriptions require verifying capital deposits inside escrow trusts against security registrations. The Transfer Agent ledger acts as the single source of truth for share registration.

28.2 Daily Audit Exports

Retrieve full ledger balances, transaction identifiers, and fee breakdowns in standardized JSON formats to reconcile against internal corporate databases.

29. Error Handling & Rate Limits

Typical HTTP responses and status structures returned by the BitGo API Gateway:

30. Wallet Creation & Management

Provision and configure digital asset wallets, generating keychains, public keys, and native deposit addresses.

30.1 Keychains & Multi-sig Generation

Creating a secure multi-sig wallet requires generating a user keychain and a backup keychain. BitGo generates the third keychain (the HSM-backed co-signing key) and links all three keychains during wallet initialization.

30.2 Provisioning a New Wallet

Submit a request to generate a 2-of-3 multi-sig wallet on the desired blockchain (e.g., Ethereum or Bitcoin Testnet):

Request Body:

{
  "label": "Corporate Treasury Wallet #1",
  "passphrase": "your-client-side-encryption-passphrase",
  "enterprise": "69a0b54edd793f289161ec0c50cee070"
}

Response Body:

{
  "id": "69a0b54edd793f289161ec0c50cee070",
  "label": "Corporate Treasury Wallet #1",
  "coin": "tbtc4",
  "keys": [
    "558aef22d3cd...",
    "28dfca182e0d...",
    "12cba82e02d8..."
  ],
  "address": "tb1q7w6xmjmdfjkwmsdn73h07gsw778h9jsw7w8s9s"
}

31. Authentication Flow & 2FA Signing

BitGo secures administrative actions and transactional spending through a multi-tier authentication model.

31.1 Access Tokens

All API calls must contain a valid Authorization Bearer header: Authorization: Bearer <access_token>. Access tokens can be whitelisted to specific IP addresses and given selective scopes (e.g., read-only, spend).

31.2 User Authentication Keys & 2FA Signing

To authorize sensitive transactions (like paying a Lightning invoice or changing enterprise policy limits), standard custody accounts require providing a User Authentication Key signature. High-value actions also require verifying a one-time password (OTP) issued via Google Authenticator or SMS.

32. Supported Coins & Tokens

BitGo supports a wide variety of native coins and minted tokens across standard multi-sig custody wallets and unified Go Accounts.

32.1 Native Coins

Mined blockchain native currencies. Wallets holding these currencies are network-specific:

• BTC / TBTC4: Bitcoin Mainnet & Testnet4
• ETH / HTETH: Ethereum Mainnet & Holesky Testnet
• SOL / TSOL: Solana Mainnet & Testnet

32.2 Minted Stablecoins & Tokens

Minted on top of base layers. Multiple tokens can co-exist inside a single wallet of the same chain:

• USD1: Native stablecoin supported on Ethereum, BSC, Tron, Solana, Aptos, and Go Accounts.
• SoFiUSD (SOFID): Pegged stablecoin supported on Ethereum, Solana, and Go Accounts.

33. Real-World Asset (RWA) Lifecycle Breakdown

The digitization and management of Real-World Assets follows four distinct steps under SEC-compliant Transfer Agent regulations:

34. Security Best Practices & Rate Limits

Ensure that B2B gateway integrations remain resilient and secure by conforming to industry best practices:

• Strict IP Whitelisting: Scope access tokens to specific API gateway IP addresses. Avoid wildcards.
• Cold Storage Thresholds: Maintain only minimum operational float in hot wallets. Route large incoming balances to secure, cold-storage vaults.
• Rate Limit Margins: The B2B gateway rate-limits API requests to 120/minute. Build exponential backoff logic into automated payment scripts to handle 429 status code returns gracefully.
• Key Rotation: Rotate access tokens periodically. Use short access token lifetimes and renew them using out-of-band oauth updates.