Skip to main content
This page is for the team connecting Musubi to your institution’s existing infrastructure — treasury systems, reconciliation, monitoring, and compliance reporting.

​
Architecture

Your Musubi integration sits alongside your existing systems: What you deploy: A Musubi backend instance (provided as a Docker container) + a PostgreSQL database. This runs in your infrastructure and connects to the settlement network. What you integrate: Your existing systems call the backend’s REST API to initiate orders and consume settlement events.

​
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

Custodian Onboarding

Confirm with your custodian that they have:
  • Connected their node to the settlement network
  • Set up your institutional custody account
  • Whitelisted the Musubi settlement address
  • Sufficient stablecoin balance for your expected volumes
3

KYC/AML Clearance

Obtain a KYC/AML clearance reference (UUID) from your compliance team. This references your existing KYC verification and is required on every order.
4

Deploy Your Backend

Deploy the Musubi backend container in your infrastructure:
  • Configure with your Party ID and JWT credentials
  • Connect to your PostgreSQL instance
  • Establish TLS connectivity to the settlement network
5

Connectivity Test

Verify your setup:
  • GET /health — confirms backend is running and connected to the network
  • GET /whoami — confirms your Party ID and role
  • Create a test order on testnet and verify it reaches SETTLED status
6

System Integration

Connect your internal systems to the backend API:
  • Order initiation from your treasury/payments system
  • Settlement events to your reconciliation system
  • Audit records to your compliance reporting

​
What to Connect

​
Order Initiation

Your treasury or payments system submits orders via POST /api/v1/orders. The key inputs:
InputSource
Receiver Party IDFrom your counterparty directory
Receiver Custodian Party IDFrom your counterparty directory
Source amountFrom your payment instruction
Target amount minimumFrom your FX risk parameters (optional cost guard)
KYC/AML referenceFrom your compliance system
Intent signatureFrom your signing infrastructure

​
Settlement Monitoring

Subscribe to real-time events via SSE (GET /api/v1/orders/events) or poll order status. Feed settlement confirmations to your reconciliation system.

​
Reconciliation

Match settled orders against your internal records using:
FieldUse
intent_idYour order reference — correlate with your internal payment ID
transaction_hashSettlement proof — store for audit and regulatory reporting
settled_atSettlement timestamp — for your accounting records
target_amount / source_amount_actualAmounts — verify against your expected values
fx_rateExecuted rate — for P&L and best execution reporting

​
Compliance Reporting

Feed the full settled order record to your compliance system. Key fields for regulatory reporting are detailed in Compliance & Audit.

​
Testing on Testnet

The testnet environment mirrors production:
  • Real network topology (each participant runs their own node)
  • Real settlement flow (atomic DvP with all four parties)
  • Mock market maker responds automatically with deterministic quotes
Test scenarios to validate:
  1. Happy path: Create order -> receive quote -> accept -> verify SETTLED
  2. Slippage guard: Set source_amount_max above the quoted amount -> verify rejection
  3. Expiry: Create order with short expiry -> verify EXPIRED status
  4. Cancellation: Create order -> cancel before quote acceptance -> verify cancellation
  5. Reconciliation: Verify transaction_hash and amounts match across your systems