# Trade model: MMCapitalIncrease

This page describes the FX Integration API's **MMCapitalIncrease** trade model, as defined in the file `config/TradingAdapter/Blade/DataSource/etc/trademodels.xml` in the FX Integration API Kit.

This documentation is for the FX Integration API 12.10.0.

Trade models are XML-defined state machines used by the [Java Trading API](https://docs.caplin.com/developer/api/trading_java/latest/) and Caplin Trader's [Trading API](../caplin-trader/4/trading-api/index.md) to manage trading workflows. For more information on trade model XML definitions, see the [Trade model XML schema](../caplin-platform/cis/cis-trade-model-schema.md) reference.

## State model

The MMCapitalIncrease trade model's state model in Mermaid JS format:

```mermaid
%% State diagram for the MMCapitalIncrease trade model
stateDiagram-v2
    [*] --> Initial
    Initial --> DetailsRequested : DetailsRequest (client)
    DetailsRequested --> DetailsProvided : DetailsUpdate (server)
    DetailsRequested --> Error : Error (server)
    DetailsRequested --> Rejected : Reject (server)
    DetailsRequested --> ClientCloseSent : ClientClose (client)
    DetailsProvided --> Submitted : Submit (client)
    DetailsProvided --> ClientCloseSent : ClientClose (client)
    Submitted --> Increased : IncreasedAck (server)
    Submitted --> Rejected : Reject (server)
    Submitted --> Error : Error (server)
    Increased --> [*] 
    Rejected --> [*] 
    Error --> [*] 
    ClientCloseSent --> ClientClosed : ClientCloseAck (server)
    ClientClosed --> [*] 
```

The MMCapitalIncrease trade model's state model in a flat state-transition matrix:

| Source state | Event trigger | Origin | Target state |
| ------------ | ------------- | ------ | ------------ |
| [*] | - | - | Initial |
| Initial | DetailsRequest | client | DetailsRequested |
| DetailsRequested | DetailsUpdate | server | DetailsProvided |
| DetailsRequested | Error | server | Error |
| DetailsRequested | Reject | server | Rejected |
| DetailsRequested | ClientClose | client | ClientCloseSent |
| DetailsProvided | Submit | client | Submitted |
| DetailsProvided | ClientClose | client | ClientCloseSent |
| Submitted | IncreasedAck | server | Increased |
| Submitted | Reject | server | Rejected |
| Submitted | Error | server | Error |
| Increased | - | - | [*] |
| Rejected | - | - | [*] |
| Error | - | - | [*] |
| ClientCloseSent | ClientCloseAck | server | ClientClosed |
| ClientClosed | - | - | [*] |

## Event message specifications

This section describes the messages sent between client and server when a state-model event occurs. The origin of an event (the client or the server) is specified in brackets after the name of the event.

The specification of some events depends on the type of financial product being traded, and when this applies, the variant specifications are detailed under level-4 headings.

Back-end developers build server events by using classes in the Caplin's FX Integration API, a Java library that makes it easy to provide data to Caplin's web applications. Where appropriate, the specifications below include references to JavaDoc documentation and code examples.

### Event: DetailsRequest (client)

Message specification:

```json
{
  "trade_model_name": "MMCapitalIncrease",
  "trade_model_trigger": "DetailsRequest",
  "message_origin": "client",
  "fields": [
    {
      "name": "MsgType",
      "type": "String",
      "flags": "",
      "definition": "Name of the transition",
      "example_value": "DetailsRequest",
      "deprecated": false
    },
    {
      "name": "RequestID",
      "type": "String",
      "flags": "",
      "definition": "The RequestID. A Unique identifier, must remain the same for each event in the trade model",
      "example_value": "",
      "deprecated": false
    },
    {
      "name": "TradeID",
      "type": "string",
      "flags": "",
      "definition": "The unique id identifying the trade.",
      "example_value": "",
      "deprecated": false
    }
  ]
}
```

### Event: ClientClose (client)

Message specification:

```json
{
  "trade_model_name": "MMCapitalIncrease",
  "trade_model_trigger": "ClientClose",
  "message_origin": "client",
  "fields": [
    {
      "name": "MsgType",
      "type": "String",
      "flags": "",
      "definition": "Name of the transition",
      "example_value": "ClientClose",
      "deprecated": false
    },
    {
      "name": "RequestID",
      "type": "String",
      "flags": "",
      "definition": "The RequestID. A Unique identifier, must remain the same for each event in the trade model",
      "example_value": "",
      "deprecated": false
    }
  ]
}
```

### Event: Submit (client)

Message specification:

```json
{
  "trade_model_name": "MMCapitalIncrease",
  "trade_model_trigger": "Submit",
  "message_origin": "client",
  "fields": [
    {
      "name": "MsgType",
      "type": "String",
      "flags": "",
      "definition": "Name of the transition",
      "example_value": "Submit",
      "deprecated": false
    },
    {
      "name": "RequestID",
      "type": "String",
      "flags": "",
      "definition": "The RequestID. A Unique identifier, must remain the same for each event in the trade model",
      "example_value": "",
      "deprecated": false
    },
    {
      "name": "PrincipalAmount",
      "type": "decimal",
      "flags": "",
      "definition": "The original amount that the trade was created with specified in the provided Currency.",
      "example_value": "",
      "deprecated": false
    }
  ]
}
```

### Event: IncreasedAck (server)

Message specification:

```json
{
  "trade_model_name": "MMCapitalIncrease",
  "trade_model_trigger": "IncreasedAck",
  "message_origin": "server",
  "java_class": "com.caplin.generated.motif.mm.tradeconfirmation.TradeConfTypesDef.TradeConfirmation",
  "javadoc": "https://docs.caplin.com/developer/api/fxintegration/com/caplin/generated/motif/mm/tradeconfirmation/TradeConfTypesDef.TradeConfirmation.html",
  "instantiation_pattern": "Builder (via .newBuilder())",
  "code_example": "https://docs.caplin.com/developer/api/fxintegration/latest/com/caplin/examples/fxapi/generated/motif/mm/tradeconfirmation/TradeConfTypesDef/TradeConfirmationExample.html",
  "parts": [
    {
      "part_name": "CommonTradeConfirmationFields",
      "java_class": "com.caplin.generated.motif.mm.tradeconfirmation.TradeConfPartsDef.CommonTradeConfirmationFields",
      "javadoc": "https://docs.caplin.com/developer/api/fxintegration/com/caplin/generated/motif/mm/tradeconfirmation/TradeConfPartsDef.CommonTradeConfirmationFields.html",
      "fields": [
        {
          "name": "TOBOUser",
          "type": "string",
          "flags": "",
          "definition": "The client who the trade is for.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "TraderUsername",
          "type": "string",
          "flags": "",
          "definition": "The name of the trader providing the price to the user, or NO_TRADER if there is none.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "Account",
          "type": "string",
          "flags": "",
          "definition": "The used account for the trade.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "Action",
          "type": "string",
          "flags": "",
          "definition": "Withdraw or deposit for Call Deposit.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "CallAccount",
          "type": "string",
          "flags": "",
          "definition": "The account which is being withdrawn from or deposited to.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "Currency",
          "type": "string",
          "flags": "",
          "definition": "The currency in which the trade is made.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "MaturityDate",
          "type": "date",
          "flags": "",
          "definition": "The maturity date of the trade.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "MaturityTenor",
          "type": "string",
          "flags": "",
          "definition": "The maturity tenor of the trade.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "StartDate",
          "type": "date",
          "flags": "",
          "definition": "The start date of the trade.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "StartTenor",
          "type": "string",
          "flags": "",
          "definition": "The start tenor of the trade.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "TradeID",
          "type": "string",
          "flags": "",
          "definition": "The unique id identifying the trade.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PrincipalAmount",
          "type": "decimal",
          "flags": "",
          "definition": "The original amount that the trade was created with specified in the provided Currency.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "InterestRate",
          "type": "decimal",
          "flags": "",
          "definition": "Interest rate on the given PrincipalAmount.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "IndicativeProfitRate",
          "type": "string",
          "flags": "",
          "definition": "Indicative profit rate on the given PrincipalAmount.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "InterestRateDPS",
          "type": "decimal",
          "flags": "",
          "definition": "The precision for a specified InterestRate.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "InterestAmount",
          "type": "decimal",
          "flags": "",
          "definition": "Interest amount (specified in the provided Currency) calculated from the interest rate and principal amount.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PrincipalPlusInterest",
          "type": "decimal",
          "flags": "",
          "definition": "Composite amount between principal amount and interest amount.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "PaymentFrequency",
          "type": "string",
          "flags": "",
          "definition": "Interest payment frequencies for term deposits, this could be ZERO-COUPON, MONTHLY, QUARTERLY, SEMI-ANNUALLY or ANNUALLY.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "AllocationMode",
          "type": "string",
          "flags": "",
          "definition": "Determines whether the amount will be alLocated to a single or multiple accounts. Supported types are [SINGLE, MULTIPLE] and is defaulted to SINGLE.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "NumberOfDays",
          "type": "string",
          "flags": "",
          "definition": "The number of days between the start and maturity dates.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ExecutionDateTime",
          "type": "string",
          "flags": "",
          "definition": "",
          "example_value": "20160322123621",
          "deprecated": false
        },
        {
          "name": "EntityId",
          "type": "string",
          "flags": "",
          "definition": "The entity the trade is on behalf of. For example, if the logged in user user1@customer.co.za wishes to make a trade on behalf of entity CUSTONE, then the value of this field will be CUSTONE. If this field is absent on a leg then the default entity should be presumed.",
          "example_value": "CUSTONE",
          "deprecated": false
        },
        {
          "name": "EntityDescription",
          "type": "string",
          "flags": "",
          "definition": "The description of a trade on behalf of entity.",
          "example_value": "Customer 1",
          "deprecated": false
        },
        {
          "name": "TradeDate",
          "type": "string",
          "flags": "",
          "definition": "",
          "example_value": "20160314",
          "deprecated": false
        },
        {
          "name": "TradingType",
          "type": "string",
          "flags": "",
          "definition": "The type of the trade. Supported types are [LOAN, DEPOSIT, CALL-DEPOSIT, TERM-DEPOSIT, FLEXI-NOTICE-DEPOSIT, TREASURY-BILL or GOVERNMENT-BOND].",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "QuoteID",
          "type": "string",
          "flags": "",
          "definition": "Unique id for a quote, used to determine which quote has been used for trade execution.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "QuoteDateTime",
          "type": "string",
          "flags": "",
          "definition": "",
          "example_value": "20160314013000",
          "deprecated": false
        },
        {
          "name": "CanAffirm",
          "type": "boolean",
          "flags": "",
          "definition": "Ability to Affirm the Trade Details are as agreed.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "DisplayFields",
          "type": "string",
          "flags": "",
          "definition": "Configuration for a frontend to display label-value pairs. Use DefaultDisplayFields builders to provide Caplin default and/or custom fields.",
          "example_value": "method={'import':'static com.caplin.motif.mm.config.DefaultDisplayFields.addDefaultMMTermSummaryDisplayFields','name':'addDefaultMMTermSummaryDisplayFields','comment':'See DefaultDisplayFields javadoc for parameters and available builder methods.'}",
          "deprecated": false
        },
        {
          "name": "CanCapitalIncrease",
          "type": "boolean",
          "flags": "",
          "definition": "Ability to Capital Increase the Trade amount.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "CanRollOver",
          "type": "boolean",
          "flags": "",
          "definition": "Ability to Roll Over the Trade amount.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "CanChangeSSI",
          "type": "boolean",
          "flags": "",
          "definition": "Ability to Change the Settlement Instructions.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "CanGiveNotice",
          "type": "boolean",
          "flags": "",
          "definition": "Ability to Give notice for Money Market trades.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "HasPostTradeHistory",
          "type": "boolean",
          "flags": "",
          "definition": "Define whether post-trade history (related deals) is available.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "NoticePeriodDescription",
          "type": "string",
          "flags": "",
          "definition": "The notice period description for the trade, sent as the raw display value or a translation token.",
          "example_value": "32 Days",
          "deprecated": false
        },
        {
          "name": "NoticePeriod",
          "type": "string",
          "flags": "",
          "definition": "The notice period for the trade.",
          "example_value": "32D",
          "deprecated": false
        },
        {
          "name": "IsShariaTrade",
          "type": "boolean",
          "flags": "",
          "definition": "Indicates whether the trade is a Sharia trade",
          "example_value": "true",
          "deprecated": false
        },
        {
          "name": "CanConfirm",
          "type": "boolean",
          "flags": "",
          "definition": "Ability to Confirm the Settlement Details are now final.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "ConfirmedBy",
          "type": "string",
          "flags": "",
          "definition": "The name of the user who confirmed a trade.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "Tags",
          "type": "string",
          "flags": "",
          "definition": "Tags for a trade.",
          "example_value": "method={'import':'static com.caplin.motif.fx.config.definitions.common.Tag','name':'Arrays.asList'}",
          "deprecated": false
        },
        {
          "name": "ConfirmedDateTime",
          "type": "datetime",
          "flags": "",
          "definition": "The time at which a trade was confirmed in ISO-8601 format",
          "example_value": "2018-03-16T07:25:16+00:00",
          "deprecated": false
        },
        {
          "name": "CanUnwind",
          "type": "boolean",
          "flags": "",
          "definition": "Ability to Unwind the Trade amount.",
          "example_value": "true",
          "deprecated": false
        },
        {
          "name": "Fees",
          "type": "decimal",
          "flags": "",
          "definition": "Fees on the given PrincipalAmount for unwind.",
          "example_value": "10.0",
          "deprecated": false
        },
        {
          "name": "ParentTradeID",
          "type": "string",
          "flags": "",
          "definition": "The unique id identifying the parent trade of this trade in the case of post trade workflows.",
          "example_value": "00002456",
          "deprecated": false
        },
        {
          "name": "NoticeGiven",
          "type": "boolean",
          "flags": "",
          "definition": "Reflects if notice has been given.",
          "example_value": "true",
          "deprecated": false
        }
      ]
    },
    {
      "part_name": "SettlementTradeFields",
      "java_class": "com.caplin.generated.motif.mm.settlementinstructions.SettlementInstructionsPartsDef.SettlementTradeFields",
      "javadoc": "https://docs.caplin.com/developer/api/fxintegration/com/caplin/generated/motif/mm/settlementinstructions/SettlementInstructionsPartsDef.SettlementTradeFields.html",
      "parts": [
        {
          "part_name": "SettlementFields",
          "java_class": "com.caplin.generated.motif.mm.settlementinstructions.SettlementInstructionsPartsDef.SettlementFields",
          "javadoc": "https://docs.caplin.com/developer/api/fxintegration/com/caplin/generated/motif/mm/settlementinstructions/SettlementInstructionsPartsDef.SettlementFields.html",
          "fields": [
            {
              "name": "Un_PaySettlementId",
              "type": "string",
              "flags": "",
              "definition": "The identifier for the settlement instruction.",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Un_PayIsDefaultSettlementInstruction",
              "type": "boolean",
              "flags": "",
              "definition": "Is this the default settlement instruction for this currency",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Un_PaySettlementInstructionType",
              "type": "string",
              "flags": "",
              "definition": "The type of settlement instruction attached to a trade. Supported types are [EXISTING, ADHOC, NONE]",
              "example_value": "EXISTING",
              "deprecated": false
            },
            {
              "name": "Un_PaySettlementType",
              "type": "string",
              "flags": "",
              "definition": "The type of settlement attached to a trade. Supported types are [PRINCIPAL, INTEREST]",
              "example_value": "PRINCIPAL",
              "deprecated": false
            },
            {
              "name": "Un_PaySettlementRemarks",
              "type": "string",
              "flags": "",
              "definition": "The remarks corresponding to the settlement details",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Un_PaySettlementDisplayName",
              "type": "string",
              "flags": "",
              "definition": "The name of the settlement instruction. This field can be omitted.",
              "example_value": "[CCY] Account 1",
              "deprecated": false
            }
          ]
        },
        {
          "part_name": "SettlementFields",
          "java_class": "com.caplin.generated.motif.mm.settlementinstructions.SettlementInstructionsPartsDef.SettlementFields",
          "javadoc": "https://docs.caplin.com/developer/api/fxintegration/com/caplin/generated/motif/mm/settlementinstructions/SettlementInstructionsPartsDef.SettlementFields.html",
          "fields": [
            {
              "name": "Un_ReceiveSettlementId",
              "type": "string",
              "flags": "",
              "definition": "The identifier for the settlement instruction.",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Un_ReceiveIsDefaultSettlementInstruction",
              "type": "boolean",
              "flags": "",
              "definition": "Is this the default settlement instruction for this currency",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Un_ReceiveSettlementInstructionType",
              "type": "string",
              "flags": "",
              "definition": "The type of settlement instruction attached to a trade. Supported types are [EXISTING, ADHOC, NONE]",
              "example_value": "EXISTING",
              "deprecated": false
            },
            {
              "name": "Un_ReceiveSettlementType",
              "type": "string",
              "flags": "",
              "definition": "The type of settlement attached to a trade. Supported types are [PRINCIPAL, INTEREST]",
              "example_value": "PRINCIPAL",
              "deprecated": false
            },
            {
              "name": "Un_ReceiveSettlementRemarks",
              "type": "string",
              "flags": "",
              "definition": "The remarks corresponding to the settlement details",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Un_ReceiveSettlementDisplayName",
              "type": "string",
              "flags": "",
              "definition": "The name of the settlement instruction. This field can be omitted.",
              "example_value": "[CCY] Account 1",
              "deprecated": false
            }
          ]
        }
      ],
      "fields": [
        {
          "name": "Un_CanAffirm",
          "type": "boolean",
          "flags": "",
          "definition": "Ability to Affirm the Trade Details are as agreed.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "Un_IsReceiveInterestSplit",
          "type": "boolean",
          "flags": "",
          "definition": "Whether the receive Settlement Instruction has been split into separate Principal and Interest instructions.",
          "example_value": "",
          "deprecated": false
        }
      ]
    }
  ]
}
```

Java class: [com.caplin.generated.motif.mm.tradeconfirmation.TradeConfTypesDef.TradeConfirmation](https://docs.caplin.com/developer/api/fxintegration/latest/com/caplin/generated/motif/mm/tradeconfirmation/TradeConfTypesDef.TradeConfirmation.html)

Instantiation pattern: Static Factory Method (via `TradeConfTypesDef.TradeConfirmation.newBuilder()`)

Java code example:

```java
package com.caplin.examples.fxapi.generated.motif.mm.tradeconfirmation.TradeConfTypesDef; 

import java.math.BigInteger;
import static com.caplin.motif.fx.config.DefaultDisplayFields.addDefaultSalesAllocationDetailsUpdateFields;
import static com.caplin.motif.fx.config.definitions.common.Tag;

import com.caplin.generated.motif.mm.settlementinstructions.SettlementInstructionsPartsDef;
import com.caplin.generated.motif.mm.tradeconfirmation.TradeConfPartsDef;
import com.caplin.generated.motif.mm.tradeconfirmation.TradeConfTypesDef;

public class TradeConfirmationExample {
    public static void main(String[] args) {
                    		
		TradeConfTypesDef.TradeConfirmation tradeConfirmation =
		TradeConfTypesDef.TradeConfirmation
			.newBuilder()
			.addSettlementTradeFields(
			SettlementInstructionsPartsDef.SettlementTradeFields
				.newBuilder()
				.setCanAffirm(true)
				.setIsReceiveInterestSplit("")
				.setPay(
				SettlementInstructionsPartsDef.SettlementFields
					.newBuilder()
					.setIsDefaultSettlementInstruction("")
					.setSettlementDisplayName("[CCY] Account 1")
					.setSettlementId("")
					.setSettlementInstructionType("EXISTING")
					.setSettlementRemarks("")
					.setSettlementType("")
					.build())
				.setReceive(
				SettlementInstructionsPartsDef.SettlementFields
					.newBuilder()
					.build())
				.build())
			.setCommonFields(
			TradeConfPartsDef.CommonTradeConfirmationFields
				.newBuilder()
				.setAccount("Garfields|GARF")
				.setAction("")
				.setAllocationMode("")
				.setCallAccount("")
				.setCanAffirm(true)
				.setCanCapitalIncrease("")
				.setCanChangeSSI(true)
				.setCanConfirm("")
				.setCanGiveNotice("")
				.setCanRollOver(true)
				.setCanUnwind("")
				.setConfirmedBy("")
				.setConfirmedDateTime("2018-03-16T07:25:16+00:00")
				.setCurrency("USD")
				.setDisplayFields(addDefaultSalesAllocationDetailsUpdateFields(/* See DefaultDisplayFields javadoc for parameters and available builder methods. */))
				.setEntityDescription("Customer 1")
				.setEntityId("CUSTONE")
				.setExecutionDateTime("20160322123621")
				.setExtraFields("")
				.setFees("")
				.setHasPostTradeHistory("")
				.setIndicativeProfitRate("")
				.setInterestAmount(BigDecimal.valueOf(0.0))
				.setInterestRate(BigDecimal.valueOf(0.0))
				.setInterestRateDPS("")
				.setIsShariaTrade("")
				.setMaturityDate(LocalDate.now())
				.setMaturityTenor("")
				.setNoticeGiven("")
				.setNoticePeriod("")
				.setNoticePeriodDescription("")
				.setNumberOfDays("")
				.setParentTradeID("")
				.setPaymentFrequency("")
				.setPrincipalAmount(BigDecimal.valueOf(0.0))
				.setPrincipalPlusInterest("")
				.setQuoteDateTime("")
				.setQuoteID("")
				.setStartDate(LocalDate.now())
				.setStartTenor("1W")
				.setTOBOUser("client@customer.co.za")
				.setTags(Arrays.asList(/* ... */))
				.setTradeDate("20160314")
				.setTradeID("00001561")
				.setTraderUsername("sales_trader@novobank.co.za")
				.setTradingType("SPOT")
				.build())
			.setSettlementTradeFields(
			SettlementInstructionsPartsDef.SettlementTradeFields
				.newBuilder()
				.build(), 0)
			.build();
            
    }
}
```

### Event: ClientCloseAck (server)

Message specification:

```json
{
  "trade_model_name": "MMCapitalIncrease",
  "trade_model_trigger": "ClientCloseAck",
  "message_origin": "server"
}
```