Skip to main content
This page covers how to connect your custody platform to Musubi and onboard your institutional clients.

​
Architecture

​
Onboarding Checklist

1

Receive Credentials

Musubi provisions your:
  • Canton Party ID — your identity on the settlement network
  • JWT signing credentials — for API authentication
  • Network connectivity details — settlement network endpoint and TLS certificates
2

Deploy Your Backend

Deploy the Musubi custodian backend in your infrastructure:
  • Configure with your Party ID and role (custodian-sender or custodian-receiver)
  • Connect to your PostgreSQL instance
  • Establish TLS connectivity to the settlement network
3

Whitelist Settlement Address

Whitelist the Musubi settlement address in your custody platform. This is the only destination that receives assets during DvP settlement. One-time setup.
4

Onboard Institutional Clients

For each institution that will use you as custodian:
  • Set up their custody account in your platform (your existing process)
  • Confirm their Canton Party ID
  • Ensure they have sufficient stablecoin balance
  • Institutions will reference your Party ID when creating orders
5

Connectivity Test

Verify your setup:
  • GET /health — confirms backend is running and connected
  • GET /whoami — confirms your Party ID and custodian role
  • Ask your integration contact to create a test order referencing your Party ID
  • Verify the order appears in GET /api/v1/orders
6

Connect Your Systems

Wire up:
  • Order events -> your custody platform (for authorization workflow)
  • Settlement events -> your client reporting system (for balance updates)
  • Audit records -> your compliance system

​
Institution Relationships

Institutions reference your Party ID (sender_custodian_party_id or receiver_custodian_party_id) when creating orders. This means:
  • You must onboard institutions first — they can’t reference you until you’ve set up their account
  • Multiple institutions can reference you as their custodian simultaneously
  • You see all orders where you are the custodian, across all your institutional clients

​
Communication with Institutions

The settlement protocol handles the authorization flow — you don’t need to coordinate per-transaction with institutions. However, establish:
  • Operational contacts — for escalation if settlement issues arise
  • Balance notifications — alert institutions when balances are low
  • Reporting cadence — agree on reconciliation format and frequency

​
Monitoring

​
Dashboard Stats

GET /api/v1/dashboard/stats provides:
MetricDescription
Orders by statusPENDING, QUOTED, EXECUTING, SETTLED, FAILED, EXPIRED counts
Settled volumeTotal JPYSC0 and USDCx settled through your custody
Recent settlementLast settlement timestamp and average settlement time

​
What to Watch

  • PENDING orders accumulating — may indicate quoting issues; check with institutions
  • FAILED orders — investigate failure_reason and alert the affected institution
  • Settlement volume spikes — ensure sufficient stablecoin balances for your clients

​
Testing on Testnet

Test scenarios to validate:
  1. Sender custodian happy path: See order proposal -> accept -> review quotes -> co-sign best quote -> verify SETTLED
  2. Receiver custodian happy path: Verify settlement confirmation arrives with correct amounts
  3. Reject order proposal: Reject a proposal and verify the order is cancelled
  4. Quote expiry: Wait for quotes to expire and verify order transitions to EXPIRED
  5. Reconciliation: Match transaction_hash, amounts, and timestamps across your systems