> ## Documentation Index
> Fetch the complete documentation index at: https://musubinetwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Guide

> Architecture, automated quoting, onboarding, and monitoring for market makers.

This page covers how to connect your pricing infrastructure to Musubi and set up automated quoting.

## Architecture

```mermaid actions=false theme={null}
graph LR
  subgraph Your Infrastructure
    PE[Pricing Engine] -->|Submit quotes| MB[Musubi Backend<br/>REST API + SSE Events]
    MB -->|Stats| RM[Risk / Monitoring]
    MB -->|Settlements| PL[P&L / Reconciliation]
    MB --> DB[Your Database]
  end
  MB -->|TLS| SN[Settlement Network]
```

## Automated Quoting

For competitive latency, subscribe to SSE events and respond programmatically:

```mermaid actions=false theme={null}
graph LR
  A[quote_request_new SSE event] --> B[Pricing engine evaluates:<br/>pair, amount, rate, spread]
  B --> C[Submit quote via API]
  C --> D[Monitor outcome via SSE]
  D --> E[quote_accepted]
  D --> F[quote_rejected]
  D --> G[quote_request_expired]
```

**Latency path**: SSE event -> your pricing logic -> API call. Institutions typically select quotes within \~3 seconds of the first quote arriving, so response time matters.

<Tip>
  Subscribe to the `quote_request_new` SSE event for the lowest-latency notification of new RFQs. Polling `GET /quote-requests` works but adds latency.
</Tip>

## Onboarding Checklist

<Steps>
  <Step title="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
  </Step>

  <Step title="Deposit Liquidity">
    Deposit USDCx sufficient for your expected quoting volume. Funds are committed only when a quote is accepted and settlement executes — pending quotes do not lock funds.
  </Step>

  <Step title="Deploy Your Backend">
    Deploy the Musubi market maker 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
  </Step>

  <Step title="Connectivity Test">
    Verify your setup:

    * `GET /health` — confirms backend is running and connected
    * `GET /whoami` — confirms your Party ID and `market-maker` role
    * `GET /quote-requests` — verify you can see active RFQs
  </Step>

  <Step title="Test Quoting">
    On testnet:

    1. Wait for a quote request (or ask your integration contact to create a test order)
    2. Submit a quote via `POST /quote-requests/{intent_id}/quotes`
    3. Verify your quote appears in `GET /quotes`
    4. If accepted, verify settlement record in `GET /settlements`
  </Step>

  <Step title="Connect Your Systems">
    Wire up:

    * SSE events -> your pricing engine (for automated quoting)
    * Settlement events -> your P\&L / reconciliation system
    * Dashboard stats -> your risk monitoring
  </Step>
</Steps>

## Monitoring

### Dashboard Stats

`GET /api/v1/dashboard/stats` returns:

| Section      | Metrics                                                                                |
| ------------ | -------------------------------------------------------------------------------------- |
| **Quoting**  | `quotes_submitted`, `quotes_accepted`, `quotes_rejected`, `quotes_expired`, `win_rate` |
| **Volume**   | `total_source_traded` (JPYSC0 received), `total_target_traded` (USDCx delivered)       |
| **Activity** | `active_quote_requests` (currently quotable)                                           |

### What to Watch

* **Win rate trending down**: your spreads may be too wide relative to competitors
* **Active requests spiking**: increased demand — ensure sufficient USDCx balance
* **Quotes expired increasing**: your `valid_until` windows may be too short, or you're quoting on requests near expiry

## Testing on Testnet

The testnet environment includes a mock institution that creates orders for testing. Scenarios to validate:

1. **Happy path**: Receive RFQ -> submit quote -> verify ACCEPTED -> verify settlement record
2. **Rejected quote**: Submit a quote with a poor rate while another MM has a better one -> verify REJECTED
3. **Quote expiry**: Submit a quote with a very short `valid_until` -> verify EXPIRED
4. **Multiple quotes**: Submit multiple quotes for the same request -> verify all tracked independently
5. **Settlement reconciliation**: Verify `mm_delivered_target_amount`, `mm_delivered_target_amount`, and `transaction_hash` in settlement record