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

# FXOrder Reference

> Every field on the FXOrder template and the records it carries through its lifecycle.

The FXOrder is Musubi's core on-ledger coordination record. This page enumerates every field on the FXOrder template and each record that binds to it through the order lifecycle.

For how the FXOrder moves through its lifecycle, see the per-role overviews and the [trust model](/compliance/trust-model).

## Enums

| Enum            | Values                                                                              |
| --------------- | ----------------------------------------------------------------------------------- |
| `Status`        | `PENDING`, `QUOTED`, `EXECUTING`, `SETTLED`, `FAILED`, `EXPIRED`                    |
| `FailureReason` | `NO_QUOTE`, `SLIPPAGE`, `TIMEOUT`, `REVERT`, `USER_CANCELLED`, `OPERATOR_WITHDRAWN` |
| `QuoteStatus`   | `QUOTE_PENDING`, `QUOTE_ACCEPTED`, `QUOTE_REJECTED`, `QUOTE_EXPIRED`                |
| `AssetType`     | `STABLECOIN_FIAT_BACKED`, `CBDC`, `COMMERCIAL_BANK_MONEY`, `CRYPTO`                 |

## `FXOrder`

Top-level template. Signatories: operator + sender's custodian. Observers: sender, receiver, receiver's custodian, and the market maker (once a quote is accepted).

| Field             | Type                     |        Optional?       | Description                                |
| ----------------- | ------------------------ | :--------------------: | ------------------------------------------ |
| `operator`        | `Party`                  |           no           | Musubi network operator (signatory)        |
| `intentId`        | `Text`                   |           no           | Unique identifier (UUID) for this order    |
| `createdAt`       | `Time`                   |           no           | Proposal creation timestamp                |
| `expiresAt`       | `Time`                   |           no           | Deadline beyond which the order expires    |
| `status`          | `Status`                 |           no           | Current lifecycle state                    |
| `sender`          | `SenderInfo`             |           no           | Sender side (party identity only)          |
| `receiver`        | `ReceiverInfo`           |           no           | Receiver side (party identity only)        |
| `sourceAsset`     | `SourceAsset`            |           no           | Asset being sold by the sender             |
| `targetAsset`     | `TargetAsset`            |           no           | Asset the receiver is to be paid in        |
| `quoteInfo`       | `QuoteInfo`              |  populated at `QUOTED` | Winning quote details                      |
| `marketMakerInfo` | `MarketMakerInfo`        |  populated at `QUOTED` | Market maker identity and quoted amounts   |
| `settlementInfo`  | `SettlementInfo`         | populated at `SETTLED` | Atomic settlement record                   |
| `failureReason`   | `Optional FailureReason` |           yes          | Set on `FAILED` or `EXPIRED`               |
| `failedAt`        | `Optional Time`          |           yes          | Timestamp captured on `FAILED` transitions |
| `memo`            | `Optional Text`          |           yes          | Free-form remittance information           |

The `ensure` clause requires `targetAmount > 0`, `expiresAt > createdAt`, a non-empty `intentId`, and valid source / target currency identifiers.

## `SenderInfo` / `ReceiverInfo`

Mirror records on either side of the trade. They carry party identity only.

| Field                                                 | Type    | Optional? | Description                                                   |
| ----------------------------------------------------- | ------- | :-------: | ------------------------------------------------------------- |
| `senderPartyId` / `receiverPartyId`                   | `Party` |     no    | Canton PartyId of the institution                             |
| `senderCustodianPartyId` / `receiverCustodianPartyId` | `Party` |     no    | Canton PartyId of the custodian                               |
| `intentSignature` *(sender only)*                     | `Text`  |     no    | Off-chain signature over the intent payload (non-repudiation) |

## `CurrencyIdentifier`

Dual-identifier scheme. `iso4217` is the three-letter reference currency; `tokenSymbol` is the on-ledger token symbol.

| Field         | Type            | Optional? | Description                                     |
| ------------- | --------------- | :-------: | ----------------------------------------------- |
| `iso4217`     | `Text`          |     no    | ISO 4217 reference currency (3 uppercase alpha) |
| `tokenSymbol` | `Text`          |     no    | On-ledger token symbol (e.g. `JPYSC0`, `USDCx`) |
| `assetType`   | `AssetType`     |     no    | Instrument classification                       |
| `issuer`      | `Optional Text` |    yes    | Human-readable issuer label                     |

## `SourceAsset` / `TargetAsset`

`SourceAsset` describes what the sender is selling; `TargetAsset` describes what the receiver is to be paid. Musubi is receiver-fixed: `targetAmount` is the primary input; market makers quote `sourceAmountMax`.

| Field                                   | Type                 | Optional? | Description                                               |
| --------------------------------------- | -------------------- | :-------: | --------------------------------------------------------- |
| `sourceCurrencyId` / `targetCurrencyId` | `CurrencyIdentifier` |     no    | Dual-identifier currency record (ISO 4217 + token symbol) |
| `sourceAmountMax` *(source only)*       | `Optional Decimal`   |    yes    | Slippage guard: max the sender will pay                   |
| `sourceAmountActual` *(source only)*    | `Optional Decimal`   |    yes    | Actual source amount debited at settlement                |
| `targetAmount` *(target only)*          | `Decimal`            |     no    | Receiver-fixed: exact amount the receiver gets            |

## `QuoteInfo`

Populated at `QUOTED`. Rate-source fields carry non-derivable market evidence at the moment the quote was captured. The fee amount itself is not stored because it is derivable: `feeAmount ≡ mmQuotedSourceAmount − (midMarketRate × targetAmount)`.

| Field              | Type               | Optional? | Description                                                         |
| ------------------ | ------------------ | :-------: | ------------------------------------------------------------------- |
| `quoteId`          | `Optional Text`    |    yes    | Winning quote identifier                                            |
| `quoteSubmittedAt` | `Optional Time`    |    yes    | When the market maker submitted the quote                           |
| `quoteAcceptedAt`  | `Optional Time`    |    yes    | When the sender accepted the quote                                  |
| `quoteValidUntil`  | `Optional Time`    |    yes    | Quote expiry (typically \~30 seconds after submission)              |
| `fxRate`           | `Optional Decimal` |    yes    | Post-spread rate actually offered                                   |
| `midMarketRate`    | `Optional Decimal` |    yes    | Observed mid-market rate at quote capture (best-execution evidence) |
| `rateSource`       | `Optional Text`    |    yes    | `REUTERS_REFINITIV` / `BLOOMBERG_BGN` / `INTERNAL_OBSERVED`         |
| `rateCapturedAt`   | `Optional Time`    |    yes    | Timestamp when the mid-market rate was observed                     |

## `MarketMakerInfo`

Populated at `QUOTED`.

| Field                  | Type               | Optional? | Description                           |
| ---------------------- | ------------------ | :-------: | ------------------------------------- |
| `marketMakerPartyId`   | `Optional Party`   |    yes    | Winning MM's Canton PartyId           |
| `mmQuotedSourceAmount` | `Optional Decimal` |    yes    | Source currency cost quoted by the MM |

## `SettlementInfo`

Populated at `SETTLED`.

| Field             | Type            | Optional? | Description                                                   |
| ----------------- | --------------- | :-------: | ------------------------------------------------------------- |
| `transactionHash` | `Optional Text` |    yes    | Canton DvP transaction hash covering all four legs atomically |
| `settledAt`       | `Optional Time` |    yes    | Settlement timestamp                                          |

## Related reading

* [Privacy](/compliance/privacy) — how per-sub-transaction privacy keeps counterparty identity off the market maker's view.
* [Trust model](/compliance/trust-model) — operator-less, four-eyes co-signature, and the atomic settlement guarantee.