# Trade model: Drawdown

This page describes the FX Integration API's **Drawdown** 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 Drawdown trade model's state model in Mermaid JS format:

```mermaid
stateDiagram-v2
%% Drawdown
    [*] --> 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 --> DetailsProvided : DetailsUpdate (server)
    Submitted --> Completed : Complete (server)
    Submitted --> Error : Error (server)
    Submitted --> Rejected : Reject (server)
    Completed --> [*]
    Error --> [*]
    Rejected --> Error : Error (server)
    ClientCloseSent --> ClientClosed : ClientCloseAck (server)
    ClientCloseSent --> Error : Error (server)
    ClientClosed --> [*]
```

The Drawdown 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 | DetailsUpdate | server | DetailsProvided |
| Submitted | Complete | server | Completed |
| Submitted | Error | server | Error |
| Submitted | Reject | server | Rejected |
| Completed | - | - | [*] |
| Error | - | - | [*] |
| Rejected | Error | server | Error |
| ClientCloseSent | ClientCloseAck | server | ClientClosed |
| ClientCloseSent | Error | server | Error |
| 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": "Drawdown",
  "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": "A unique identifier for this trade",
      "example_value": "00001561",
      "deprecated": false
    }
  ]
}
```

### Event: ClientClose (client)

Message specification:

```json
{
  "trade_model_name": "Drawdown",
  "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": "Drawdown",
  "trade_model_trigger": "Submit",
  "message_origin": "client",
  "parts": [
    {
      "part_name": "DrawdownSubmission",
      "parts": [
        {
          "part_name": "DrawdownSubmissionLeg",
          "fields": [
            {
              "name": "Ln_Amount",
              "type": "decimal",
              "flags": "",
              "definition": "The amount of a trade or order in the DealtCurrency.",
              "example_value": "",
              "deprecated": false
            },
            {
              "name": "Ln_SettlementDate",
              "type": "string",
              "flags": "",
              "definition": "The date on which the two currencies in the FX trade are exchanged. Can be a tenor or a broken date, i.e. SPOT or 20160314.",
              "example_value": "20160314",
              "deprecated": false
            },
            {
              "name": "Ln_Tenor",
              "type": "string",
              "flags": "",
              "definition": "Supported types are [ON, [TODAY, TOD, TD], TN, [TOM, ND], SPOT, SN, 1D, 1W, 2W, 3W, 4W, 1M, 2M, 4M, 5M, 6M, 7M, 8M, 9M, 10M, 11M, [1Y, 12M], 15M, 18M, 21M, [2Y, 24M], [3Y, 36M], [4Y, 48M], [5Y, 60M], broken]. 'broken' indicates that the settlement date does not fall onto a tenor.",
              "example_value": "1M",
              "deprecated": false
            }
          ]
        }
      ],
      "fields": [
        {
          "name": "TradeID",
          "type": "string",
          "flags": "",
          "definition": "A unique identifier for this trade",
          "example_value": "00001561",
          "deprecated": false
        }
      ]
    }
  ],
  "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
    }
  ]
}
```


### Event: DetailsUpdate (server)

Message specification:

```json
{
  "trade_model_name": "Drawdown",
  "trade_model_trigger": "DetailsUpdate",
  "message_origin": "server",
  "java_class": "com.caplin.generated.motif.fx.drawdown.DrawdownTypeDef.DrawdownDetails",
  "javadoc": "https://docs.caplin.com/developer/api/fxintegration/com/caplin/generated/motif/fx/drawdown/DrawdownTypeDef.DrawdownDetails.html",
  "instantiation_pattern": "Builder (via .newBuilder())",
  "code_example": "https://docs.caplin.com/developer/api/fxintegration/latest/com/caplin/examples/fxapi/generated/motif/fx/drawdown/DrawdownTypeDef/DrawdownDetailsExample.html",
  "parts": [
    {
      "part_name": "DrawdownDetailsLegFields",
      "java_class": "com.caplin.generated.motif.fx.drawdown.DrawdownPartsDef.DrawdownDetailsLegFields",
      "javadoc": "https://docs.caplin.com/developer/api/fxintegration/com/caplin/generated/motif/fx/drawdown/DrawdownPartsDef.DrawdownDetailsLegFields.html",
      "fields": [
        {
          "name": "Ln_AllInRate",
          "type": "decimal",
          "flags": "",
          "definition": "The final client rate that is made up of the spot rate + any additional costs or adjustments such as swap points or margin.",
          "example_value": "1.091790",
          "deprecated": false
        },
        {
          "name": "Ln_Amount",
          "type": "decimal",
          "flags": "",
          "definition": "The amount of a trade or order in the DealtCurrency.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "Ln_BuySell",
          "type": "string",
          "flags": "",
          "definition": "The direction of the trade or trade leg, from the client's perspective. This always refers to the BaseCurrency, NOT the DealtCurrency.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "Ln_RemainingAmount",
          "type": "decimal",
          "flags": "",
          "definition": "The amount remaining on a trade or order which can reduce after performing a post trade action/an order is filled.",
          "example_value": "500",
          "deprecated": false
        },
        {
          "name": "Ln_StartDate",
          "type": "string",
          "flags": "",
          "definition": "The date of which the time option becomes active from.",
          "example_value": "20150620",
          "deprecated": false
        },
        {
          "name": "Ln_StartTenor",
          "type": "string",
          "flags": "",
          "definition": "The tenor of which the time option becomes active from.",
          "example_value": "1W",
          "deprecated": false
        },
        {
          "name": "Ln_SettlementDate",
          "type": "string",
          "flags": "",
          "definition": "The date on which the two currencies in the FX trade are exchanged. Can be a tenor or a broken date, i.e. SPOT or 20160314.",
          "example_value": "20160314",
          "deprecated": false
        },
        {
          "name": "Ln_Tenor",
          "type": "string",
          "flags": "",
          "definition": "Supported types are [ON, [TODAY, TOD, TD], TN, [TOM, ND], SPOT, SN, 1D, 1W, 2W, 3W, 4W, 1M, 2M, 4M, 5M, 6M, 7M, 8M, 9M, 10M, 11M, [1Y, 12M], 15M, 18M, 21M, [2Y, 24M], [3Y, 36M], [4Y, 48M], [5Y, 60M], broken]. 'broken' indicates that the settlement date does not fall onto a tenor.",
          "example_value": "1M",
          "deprecated": false
        }
      ]
    }
  ],
  "fields": [
    {
      "name": "TradeID",
      "type": "string",
      "flags": "",
      "definition": "A unique identifier for this trade",
      "example_value": "00001561",
      "deprecated": false
    },
    {
      "name": "CurrencyPair",
      "type": "string",
      "flags": "",
      "definition": "The currency pair for the trade. For example, EURUSD",
      "example_value": "",
      "deprecated": false
    },
    {
      "name": "DealtCurrency",
      "type": "string",
      "flags": "",
      "definition": "The currency of the Amount of a trade or order.",
      "example_value": "GBP",
      "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.fx.config.DefaultDisplayFields.addDefaultSalesAllocationDetailsUpdateFields','name':'addDefaultSalesAllocationDetailsUpdateFields','comment':'See DefaultDisplayFields javadoc for parameters and available builder methods.'}",
      "deprecated": false
    }
  ]
}
```

Java class: [com.caplin.generated.motif.fx.drawdown.DrawdownTypeDef.DrawdownDetails](https://docs.caplin.com/developer/api/fxintegration/latest/com/caplin/generated/motif/fx/drawdown/DrawdownTypeDef.DrawdownDetails.html)

Instantiation pattern: Static Factory Method (via `DrawdownTypeDef.DrawdownDetails.newBuilder()`)

Java code example:

```java
package com.caplin.examples.fxapi.generated.motif.fx.drawdown.DrawdownTypeDef; 

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

import com.caplin.generated.motif.fx.drawdown.DrawdownPartsDef;
import com.caplin.generated.motif.fx.drawdown.DrawdownTypeDef;

public class DrawdownDetailsExample {
    public static void main(String[] args) {
                    		
		DrawdownTypeDef.DrawdownDetails drawdownDetails =
		DrawdownTypeDef.DrawdownDetails
			.newBuilder()
			.addLegFields(
			DrawdownPartsDef.DrawdownDetailsLegFields
				.newBuilder()
				.setAllInRate(BigDecimal.valueOf(1.091790))
				.setAmount(BigDecimal.valueOf(0))
				.setBuySell("")
				.setRemainingAmount("500")
				.setSettlementDate("20160314")
				.setStartDate("20150620")
				.setStartTenor("1W")
				.setTenor("1M")
				.build())
			.setCurrencyPair("")
			.setDealtCurrency("GBP")
			.setDisplayFields(addDefaultSalesAllocationDetailsUpdateFields(/* See DefaultDisplayFields javadoc for parameters and available builder methods. */))
			.setTradeID("00001561")
			.build();
            
    }
}
```

### Event: Complete (server)

Message specification:

```json
{
  "trade_model_name": "Drawdown",
  "trade_model_trigger": "DetailsUpdate",
  "message_origin": "server",
  "java_class": "com.caplin.generated.motif.fx.drawdown.DrawdownTypeDef.DrawdownConfirmation",
  "javadoc": "https://docs.caplin.com/developer/api/fxintegration/com/caplin/generated/motif/fx/drawdown/DrawdownTypeDef.DrawdownConfirmation.html",
  "instantiation_pattern": "Builder (via .newBuilder())",
  "code_example": "https://docs.caplin.com/developer/api/fxintegration/latest/com/caplin/examples/fxapi/generated/motif/fx/drawdown/DrawdownTypeDef/DrawdownConfirmationExample.html",
  "parts": [
    {
      "part_name": "DrawdownConfirmationLegFields",
      "java_class": "com.caplin.generated.motif.fx.drawdown.DrawdownPartsDef.DrawdownConfirmationLegFields",
      "javadoc": "https://docs.caplin.com/developer/api/fxintegration/com/caplin/generated/motif/fx/drawdown/DrawdownPartsDef.DrawdownConfirmationLegFields.html",
      "fields": [
        {
          "name": "Ln_Amount",
          "type": "decimal",
          "flags": "",
          "definition": "The amount of a trade or order in the DealtCurrency.",
          "example_value": "",
          "deprecated": false
        },
        {
          "name": "Ln_ContraAmount",
          "type": "decimal",
          "flags": "",
          "definition": "The amount that is exchanged for the Amount. This will be defined in the contra currency of the DealtCurrency.",
          "example_value": "350",
          "deprecated": false
        },
        {
          "name": "Ln_SettlementDate",
          "type": "string",
          "flags": "",
          "definition": "The date on which the two currencies in the FX trade are exchanged. Can be a tenor or a broken date, i.e. SPOT or 20160314.",
          "example_value": "20160314",
          "deprecated": false
        }
      ]
    }
  ],
  "fields": [
    {
      "name": "RemainingAmount",
      "type": "decimal",
      "flags": "",
      "definition": "The amount remaining on a trade or order which can reduce after performing a post trade action/an order is filled.",
      "example_value": "500",
      "deprecated": false
    },
    {
      "name": "CurrencyPair",
      "type": "string",
      "flags": "",
      "definition": "The currency pair for the trade. For example, EURUSD",
      "example_value": "",
      "deprecated": false
    },
    {
      "name": "DealtCurrency",
      "type": "string",
      "flags": "",
      "definition": "The currency of the Amount of a trade or order.",
      "example_value": "GBP",
      "deprecated": false
    }
  ]
}
```

Java class: [com.caplin.generated.motif.fx.drawdown.DrawdownTypeDef.DrawdownConfirmation](https://docs.caplin.com/developer/api/fxintegration/latest/com/caplin/generated/motif/fx/drawdown/DrawdownTypeDef.DrawdownConfirmation.html)

Instantiation pattern: Static Factory Method (via `DrawdownTypeDef.DrawdownConfirmation.newBuilder()`)

Java code example:

```java
package com.caplin.examples.fxapi.generated.motif.fx.drawdown.DrawdownTypeDef; 

import java.math.BigInteger;

import com.caplin.generated.motif.fx.drawdown.DrawdownPartsDef;
import com.caplin.generated.motif.fx.drawdown.DrawdownTypeDef;

public class DrawdownConfirmationExample {
    public static void main(String[] args) {
                    		
		DrawdownTypeDef.DrawdownConfirmation drawdownConfirmation =
		DrawdownTypeDef.DrawdownConfirmation
			.newBuilder()
			.addLegFields(
			DrawdownPartsDef.DrawdownConfirmationLegFields
				.newBuilder()
				.setAmount("0")
				.setContraAmount(BigDecimal.valueOf(500))
				.setSettlementDate("20160314")
				.build())
			.setCurrencyPair("")
			.setDealtCurrency("GBP")
			.setRemainingAmount("500")
			.build();
            
    }
}
```

### Event: ClientCloseAck (server)

Message specification:

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