## Messages

### Session

#### FIX messages

| Sender | Message Name | Type | Comments |
|  --- | --- | --- | --- |
| Client | Logon | A | Logon with username and password |
| Server | Logon | A | Logon confirmation |
| Both | Logout | 5 | Logout request/confirmation |
| Both | Heartbeat | 0 | Heart beat message sent periodically by each party to verify connection is still up, in the event no data has been received after (default) 30 seconds |
| Both | TestRequest | 1 | Test request |



```mermaid
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: Logon
    Note over C,S: Logon procedure
    activate S
    S-->>C: Logon
    S-->>C: Reject
    deactivate S

    C->>S: Logout
    activate S
    Note over C,S: Logout procedure
    S-->>C: Logout
    deactivate S

    C->>S: TestRequest
    Note over C,S: Test procedure
    activate S
    S-->>C: Heartbeat
    deactivate S
```

**Logon - A**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 98 | EncryptMethod | Y | int | 0=None |
| 108 | HeartBtInt | Y | int | Heart beat interval, seconds |
| 553 | UserName | Y | string | Client user name |
| 554 | Password | Y | string | Client password |
| 141 | ResetSeqNumFlag | Y | bool | Yes (true), FIX message sequence numbers will start from 1 on each session |


**Reject - 3**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 45 | RefSeqNum | Y | int | MsqSeqNum<34> of the rejected message |
| 371 | RefTagID | N | int | Tag number of the offending tag in the rejected message |
| 372 | RefMsgType | N | string | MsgType<35> of the rejected message |
| 373 | SessionRejectReason | N | int | Rejection code |
| 58 | Text | N | string | Error message |


**Logout - 5**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 58 | Text | N | string | Logout text message |


**Test - 1**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 112 | TestReqID | Y | string | Identifier, or 'hello world' text to be returned in ensuing Heartbeat |


**Heartbeat - 0**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 112 | TestReqID | N | string | Only required if it is in a reply to a Test message |


### Orders

#### Instant Execution

BTCS supports three order types for instant execution; all with FOK (Fill or Kill) as Time-in-Force:

- Market: Plain vanilla market order.
- Limit: Either the entire order can be filled within the limit set on the order, or it will be rejected.
- Quote: The client asks for a quote, i.e. a guaranteed price to buy or sell a given quantity of an instrument. Given a quote id, the client can then submit an order and will be filled accordingly.


#### Event Driven Execution

BTCS supports two order types for market price driven execution; both with GTC (Good Till Cancel) as Time-in-Force:

- Limit:
  - For sell orders: Sell the entire order quantiy at a minimum price.
  - For buy orders: Buy the entire order quantity at a maximum price.
- Stop:
  - For sell orders: If the top-of-book bid price touches the order stop price, or is lower, then the order will be filled as plain vanilla market order.
  - For buy orders: If the top-of-book offer price touches the order stop price, or is higher, then the order will be filled as plain vanilla market order.


#### Strategy Execution

For execution strategies beyond the vanilla types above, BTCS supports **Smart** target strategy for advanced execution. Here, the order is fed to the market bit-by-bit throughout a time period which aims to give the client, on average, the best price in the market. This is intended for larger orders.

#### Cancellation

The client can at any time cancel an open order, which will cancel any attempts to fill the remaining quantity on the order.

#### Best Execution Policy

All orders are executed according to our Best Execution policy.

### FIX messages

| Sender | Message Name | Type | Comments |
|  --- | --- | --- | --- |
| Client | QuoteRequest | R | Request for tradeable quote |
| Server | Quote | S | Tradeable quote |
| Server | QuoteRequestReject | AG | Rejection of quote request |
| Client | NewOrderSingle | D | New order |
| Server | ExecutionReport | 8 | Status on an order, including acceptance, fills, cancellations and rejects |
| Client | OrderStatusRequest | H | Request for status on an individual order |
| Client | OrderMassStatusRequest | AF | Request for status on all orders |
| Client | OrderCancelRequest | F | Request to cancel an order |
| Server | OrderCancelReject | 9 | Rejection message, if an order could not be cancelled or modified |


**Quote trading**


```mermaid NewOrderSingle(Quote)
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: QuoteRequest
    Note over C,S: Quote request procedure
    activate S
    alt all good
        S-->>C: Quote
    else in case of error
        S-->>C: QuoteRequestReject
    end
    deactivate S

    C->>S: NewOrderSingle(Quote)
    Note over C,S: Quote order procedure
    activate S
    alt all good
        S-->>C: ExecutionReport(Filled)
    else in case of error
        S-->>C: ExecutionReport(Rejected)
    end
    deactivate S
```

**Market and Limit Orders (FOK)**


```mermaid NewOrderSingle(TimeInForce=FOK)
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: NewOrderSingle(1=Market or 2=Limit | FOK)
    Note over C,S: Instant Market or Limit order procedure
    alt all good
        S-->>C: ExecutionReport(New)
        loop for each fill except for the last one
            S-->>C: ExecutionReport(PartiallyFilled)
        end
        alt Order could be fully filled (FOK)
            S-->>C: ExecutionReport(Filled)
        else not enough liquidity (at the price limit)
            S-->>C: ExecutionReport(Rejected)
        end
    else in case of error or for FOK, not enough liquidity
        S-->>C: ExecutionReport(Rejected)
    end
```

**Limit, Stop, and Strategy Orders (GTC) - full accept**


```mermaid NewOrderSingle(TimeInForce=GTC)
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: NewOrderSingle(GTC)
    Note over C,S: Event driven procedure
    alt all good, fully accepted
        S-->>C: ExecutionReport(New)
    else in case of error
        S-->>C: ExecutionReport(Rejected)
    end
```

**Limit, Stop, and Strategy Orders (GTC) - pending accept**


```mermaid NewOrderSingle(TimeInForce=GTC)
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: NewOrderSingle(GTC)
    Note over C,S: Event driven procedure
    alt partially good, pending full acceptance
        S-->>C: ExecutionReport(PendingNew)
        alt later full acceptance by trading desk
            S-->>C: ExecutionReport(New)
        else problem with the order
            S-->>C: ExecutionReport(Rejected)
        end
    end
```

**Order Status**


```mermaid OrderStatusRequest
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: OrderStatusRequest
    Note over C,S: Status on single order procedure
    alt order exists
        S-->>C: ExecutionReport(New)
    else order was cancelled
        S-->>C: ExecutionReport(Cancelled)
    end
    opt order does not exist
    S-->>C: Reject
    end
```


```mermaid OrderMassStatusRequest
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: OrderMassStatusRequest
    Note over C,S: Status on all orders procedure
    activate S
    loop For each client order
        S-->>C: ExecutionReport
    end
    deactivate S
```

**Cancellation**


```mermaid OrderCancelRequest
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: OrderCancelRequest
    Note over C,S: Order cancellation procedure
    alt order can be cancelled
        S-->>C: ExecutionReport(PendingCancel)
        S-->>C: ExecutionReport(Cancelled)
    else in case of error
        S-->>C: OrderCancelReject
    end
```

**QuoteRequest - R**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 1 | Account | Y | string | Account where the amount is to be deducted from; debited |
| 131 | QuoteReqID | Y | string | Unique identifier for this request |
| 146 | NoRelatedSym | Y | int | 1. Number of symbols in this request. BTCS only supports a quote for a single instrument |
| >55 | Symbol | Y | string | ccyA/ccyB |
| >38 | OrderQty | Y | decimal | Must be positive and specifies the quantity in currency the client wants to buy or sell |
| >15 | Currency | Y | string | Either ccyA or ccyB |
| >54 | Side | N | char | 1=Buy2=SellIf set, the calculated commission amount is an exact amount otherwise an estimate |
| >8007 | QtyIncludesComm | N | bool | Quantity should include the commission amount |


**Quote - S**

The quote defines the bid- and offer prices that the client can expect to be filled at for the requested quantity and currency.

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 117 | QuoteID | Y | string | BTCS assigned id for this quote |
| 131 | QuoteReqID | Y | string | Client's QuoteRequest ID this quote refers to |
| 15 | Currency | Y | string | Either ccyA or ccyB |
| 38 | OrderQty | Y | decimal | The quantity to be traded |
| 55 | Symbol | Y | string | ccyA/ccyB |
| 132 | BidPx | Y | decimal | Bid price |
| 133 | OfferPx | Y | decimal | Offer price |
| 126 | ExpireTime | Y | UTC Timestamp | When the quote expires |
| 60 | TransactTime | Y | UTC Timestamp | Timestamp with 3 decimals when the report was created |


**QuoteRequestReject -AG**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 131 | QuoteReqID | Y | string | Client's QuoteRequest ID this quote refers to |
| 658 | QuoteRequestRejectReason | Y | int | Unique rejection code |
| 58 | Text | N | string | Error description |


**NewOrderSingle Fields**

The below is a summary of the various mandatory (m) and optional (o) order fields to support the different order and execution types.

| Tag | Field Name | Market Instant | Limit Instant | RFQ Instant | Smart | Limit | Stop |
|  --- | --- | --- | --- | --- | --- | --- | --- |
| 1 | Account | m | m | m | m | m | m |
| 11 | ClOrdID | m | m | m | m | m | m |
| 15 | Currency | m | m | m | m | m | m |
| 38 | OrderQty | m | m | m | m | m | m |
| 55 | Symbol | m | m | m | m | m | m |
| 54 | Side | m | m | m | m | m | m |
| 60 | TransactionTime | m | m | m | m | m | m |
| 117 | QuoteID |  |  | m |  |  |  |
| 40 | OrdType | Market | Limit | PreivouslyQuoted | Market | Limit | Stop |
| 59 | TimeInForce | FOK | FOK | FOK | GTC | GTC | GTC |
| 847 | TargetStrategy |  |  |  | Smart |  |  |
| 126 | ExpireTime |  |  |  | o | m | m |
| 44 | Price |  | m |  |  | m |  |
| 99 | StopPx |  |  |  |  |  | m |


**NewOrderSingle - D**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 1 | Account | Y | string | Account where the amount is to be deducted from; debited |
| 11 | ClOrdID | Y | string | Unique client order |
| 15 | Currency | Y | string | Either ccyA or ccyB |
| 38 | OrderQty | Y | decimal | Must be positive, and specifies the quantity the client wants to buy or sell, in currency |
| 40 | OrdType | Y | char | 1=Market2=Limit3=StopD=Previously quoted |
| 44 | Price | N | decimal | Limit price |
| 99 | StopPx | N | decimal | Stop price |
| 54 | Side | Y | char | 1=Buy2=Sell |
| 55 | Symbol | Y | string | ccyA/ccyB |
| 59 | TimeInForce | Y | char | 4=Fill or Kill1=Good Till Cancel |
| 60 | TransactTime | Y | UTC Timestamp | Timestamp with 3 decimals when the order was created |
| 117 | QuoteID | N | string | BTCS assigned id for quote that should be executed. Only relevant when OrdType=D=Previously quoted |
| 126 | ExpireTime | N | UTC Timestamp | ExpireTime (UTC) (For GTC) |
| 847 | TargetStrategy | N | int | 0=None100=Smart101=TWAP102=Scheduled103=SoftLimit104=DCA |
| 8004 | ToAccount | N | string | 2nd account, if it cannot be deduced from the symbol. Account where the amount will be credited to |
| 8007 | QtyIncludesComm | N | bool | Quantity should include the commission amount |


**ExecutionReport - 8 - Normal case**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 1 | Account | Y | string | Account where the amount is to be deducted from; debited |
| 11 | ClOrdID | Y | string | Unique client order, eiter from NewOrderSingle, OrderCancelRequest, or OrderCancelReplaceRequest |
| 41 | OrigClOrdID | Y | string | Original client order that was cancelled or modified |
| 37 | OrderID | Y | string | BTCS assigned order Id |
| 117 | QuoteID | N | string | BTCS assigned quote Id |
| 40 | OrdType | Y | char | 1=Market2=Limit3=StopD=Previously quoted |
| 44 | Price | N | decimal | Limit price |
| 99 | StopPx | N | decimal | Stop price |
| 54 | Side | Y | char | 1=Buy2=Sell |
| 55 | Symbol | Y | string | ccyA/ccyB |
| 59 | TimeInForce | Y | char | 4=Fill or Kill (Market, Limit, PreviouslyQuoted)1=Good Till Cancel (Market, Limit, Stop, StopLimit) |
| 15 | Currency | Y | string | Original order currency |
| 38 | OrderQty | Y | decimal | Original order quantity |
| 17 | ExecID | Y | string | BTCS assigned execution ID to uniquely identify this execution |
| 150 | ExecType | Y | char | 0=New4=Cancelled5=Replaced8=RejectedF=Trade (fill or partial fill)I=Order status |
| 39 | OrdStatus | Y | char | A=PendingNew0=New1=PartiallyFilled2=Filled4=Cancelled6=PendingCancel8=Rejected |
| 31 | LastPx | N | decimal | The price for this particular fill |
| 32 | LastQty | N | decimal | The quantity in currency for this particular fill |
| 14 | CumQty | N | decimal | Cumulative sum of the fills for this order |
| 151 | LeavesQty | N | decimal | Quantity - Cumulative quantity |
| 60 | TransactTime | Y | UTC Timestamp | Timestamp with 3 decimals when the report was created |
| 126 | ExpireTime | N | UTC Timestamp | ExpireTime (UTC) |
| 847 | TargetStrategy | N | int | 0=None100=Smart |
| 103 | OrdRejReason | N | int | Unique error code if the order was rejected |
| 58 | Text | N | string | Error description |
| 8012 | AvailableToTrade | N | decimal | If TradingPolicy is violated, this is a hint what could be traded instead |
| 479 | CommCurrency | N | string | Commission currency |
| 12 | Commission | N | decimal | Commission amount |
| 584 | MasStatusReqID | N | string | Client provided request ID, if in a reply to OrderMassStatusRequest |
| 911 | TotNumReports | N | int | Total number of reports to be replied, if in a reply to OrderMassStatusRequest |
| 912 | LastRptRequested | N | bool | Is this the last report, if in a reply to OrderMassStatusRequest |


**ExecutionReport - 8 - Empty reply to OrderMassStatusRequest**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 17 | ExecID | Y | string | BTCS assigned execution ID to uniquely identify this execution |
| 150 | ExecType | Y | char | I=Order status |
| 60 | TransactTime | Y | UTC Timestamp | Timestamp with 3 decimals when the report was created |
| 584 | MasStatusReqID | Y | string | Client provided request ID, if in a reply to OrderMassStatusRequest |
| 911 | TotNumReports | Y | int | 0 |
| 912 | LastRptRequested | Y | bool | Y |


**OrderStatusRequest - H**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 1 | Account | Y | string | Account used for the order |
| 11 | ClOrdID | Y | string | Client order Id this request refers to |


**OrderMassStatusRequest - AF**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 1 | Account | Y | string | An account that was used for one of the orders |
| 584 | MasStatusReqID | Y | string | Client provided request ID |
| 585 | MassStatusReqType | Y | int | 7=All orders11=Open orders |


**OrderCancelRequest - F**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 1 | Account | Y | string | Account used for the order |
| 11 | ClOrdID | Y | string | Unique identifier for this request |
| 41 | OrigClOrdID | Y | string | Client order Id of the order that should be cancelled |
| 60 | TransactTime | Y | UTC Timestamp | Timestamp with 3 decimals when the request was created |


**OrderCancelReject - 9**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 11 | ClOrdID | Y | string | Unique identifier for the cancellation request |
| 41 | OrigClOrdID | Y | string | Client order Id of the order that should be cancelled |
| 39 | OrdStatus | Y | char | 8=Rejected |
| 102 | CxlRejReason | N | int | Rejection code |
| 58 | Text | N | string | Rejection description |
| 434 | CxlRejResponseTo | Y | char | 1=OrderCancelRequest2=OrderCancelReplaceRequest |


### Market Data

| Sender | Message Name | Type | Comments |
|  --- | --- | --- | --- |
| Client | MarketDataRequest | V | Request to subscribe and unsubscribe to market data |
| Server | MarketDataRequestReject | Y | Rejection of market data request |
| Server | MarketDataSnapshotFullRefresh | W | Market data with the option to inlcude only top-of-book or full-book |



```mermaid Subscribe
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: MarketDataRequest(Subscribe)
    Note over C,S: MarketData subscription procedure
    alt all good
        loop streaming prices
            S-->>C: MarketDataSnapshotFullRefresh
        end
    else in case of error
        S-->>C: MarketDataRequestReject
    end
```


```mermaid Unsubscribe
sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: MarketDataRequest(Unsubscribe)
    Note over C,S: MarketData un-subscription procedure
    alt all good
        Note over S: Server simply stops sending prices
    else in case of error
        S-->>C: MarketDataRequestReject
    end
```

**MarketDataRequest - V**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 262 | MDReqID | Y | string | Unique identifier for the market data request. It is allowed to use the symbol, e.g. BTCUSD, as request id |
| 263 | SubscriptionRequestType | Y | char | 1=Subsribe2=Unsubscribe |
| 264 | MarketDepth | Y | int | 0=Full Book1=Top of Book |
| 265 | MDUpdateType | Y | int | 0=Full Refresh |
| 267 | NoMDEntryTypes | Y | int | 2. Client wants both Bid and Offer prices. Client must specify two MDEntryType fields |
| >269 | MDEntryType | Y | char | 0=Bid1=Offer |
| 146 | NoRelatedSym | Y | int | 1. Number of symbols in this request. |
| >55 | Symbol | Y | string | ccyA/ccyB |


**MarketDataRequestReject - Y**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 262 | MDReqID | Y | string | Unique identifier for the market data request |
| 58 | Text | N | string | Reject reason |
| 8001 | MarketDataRejectionCode | N | int | Unique code for the reason for the rejection |


**MarketDataSnapshotFullRefresh - W**

| Tag | Field Name | Required | Type | Comments |
|  --- | --- | --- | --- | --- |
| 262 | MDReqID | Y | string | Unique identifier for the market data request |
| 55 | Symbol | Y | string | ccyA/ccyB |
| 268 | NoMDEntries | Y | int | Number of market data entries in this message |
| >269 | MDEntryType | Y | char | 0=Bid1=Offer |
| >270 | MDEntryPx | Y | decimal | Price |
| >271 | MDEntrySize | Y | decimal | Quantity |
| >8002 | VenueID | N | int | Id of the execution venue offering this price |


### Custom FIX Fields

These fields are in addition to the FIX standard.

| Tag | Field Name | Type | Comments |
|  --- | --- | --- | --- |
| 8001 | MarketDataRejectionCode | int | Unique code for the reason for the rejection |
| 8002 | VenueID | int | Id of the execution venue offering this price |
| 8004 | ToAccount | string | 2nd account, if it cannot be deduced from the symbol. Account where the amount will be credited to |
| 8007 | QtyIncludesComm | bool | Quantity should include the commission amount |
| 8012 | AvailableToTrade | decimal | If TradingPolicy is violated, this is a hint what could be traded instead |