Merge pull request #2 from scripbox/feature/fetch-funds-and-margin

Add funds and margins API

Author: sahil290791

README.md

@@ -33,6 +33,7 @@ end
 - Cancel an Order
 - Retrieve orders
 - Retrieve holdings
+- Retrieve funds and margins
 - Retrieve positions
 - Postback
 - Logout

lib/kite_connect_ex.ex

@@ -94,4 +94,14 @@ defmodule KiteConnectEx do
   """
   @spec instruments(String.t(), String.t()) :: {:ok, List.t()} | Response.error()
   defdelegate instruments(access_token, exchange), to: Instrument
+
+  @doc """
+  Get user's margins `funds_and_margins`
+
+  ## Example
+
+    {:ok, funds_and_margins} = KiteConnectEx.funds_and_margins("access-token", "equity")
+  """
+  @spec funds_and_margins(String.t(), String.t()) :: {:ok, List.t()} | Response.error()
+  defdelegate funds_and_margins(access_token, segment_type), to: User
 end

lib/kite_connect_ex/response.ex

@@ -7,7 +7,6 @@ defmodule KiteConnectEx.Response do
   @success_status "success"
   @error_status "error"
 
-
   @csv_content_type {"Content-Type", "text/csv"}
 
   @doc false

lib/kite_connect_ex/user.ex

@@ -6,9 +6,11 @@ defmodule KiteConnectEx.User do
   """
 
   alias KiteConnectEx.Request
+  alias KiteConnectEx.User.FundAndMargin
 
   @login_url "https://kite.zerodha.com/connect/login"
   @create_session_path "/session/token"
+  @funds_and_margins_path "/user/margins"
 
   @keys [
     access_token: nil,
@@ -71,6 +73,32 @@ defmodule KiteConnectEx.User do
     {:ok, login_url}
   end
 
+  @doc """
+  Get user's funds and margins of segments: "equity" || "commodity"
+  default segment_type: equity
+
+  ## Example
+
+    {:ok, funds_and_margins} = KiteConnectEx.User.funds_and_margins("access-token")
+
+    {:ok, funds_and_margins} = KiteConnectEx.User.funds_and_margins("access-token", "commodity")
+  """
+  @spec funds_and_margins(String.t(), String.t()) :: {:ok, %__MODULE__{}} | Response.error()
+  def funds_and_margins(access_token, segment_type \\ "equity") when is_binary(access_token) do
+    url = @funds_and_margins_path <> "/" <> segment_type
+
+    Request.get(url, nil, auth_header(access_token), KiteConnectEx.request_options())
+    |> case do
+      {:ok, data} ->
+        funds_and_margins = FundAndMargin.new(data)
+
+        {:ok, funds_and_margins}
+
+      {:error, error} ->
+        {:error, error}
+    end
+  end
+
   @doc """
   Generate `access_token` using the `request_token`
 
@@ -128,4 +156,8 @@ defmodule KiteConnectEx.User do
   defp new(_) do
     struct(__MODULE__, %{})
   end
+
+  defp auth_header(access_token) do
+    [{"Authorization", "token " <> KiteConnectEx.api_key() <> ":" <> access_token}]
+  end
 end

lib/kite_connect_ex/user/fund_and_margin.ex

@@ -0,0 +1,40 @@
+defmodule KiteConnectEx.User.FundAndMargin do
+  alias KiteConnectEx.User.FundAndMargin.AvailableSegment
+  alias KiteConnectEx.User.FundAndMargin.UtilisedSegment
+
+  @moduledoc """
+  Module to represent an fund and margin resource
+
+  - [Docs](https://kite.trade/docs/connect/v3/user/#funds-and-margins)
+  """
+
+  @keys [
+    enabled: false,
+    net: nil,
+    available: nil,
+    utilised: nil
+  ]
+
+  @type t :: %__MODULE__{
+          enabled: Bool.t(),
+          net: Float.t(),
+          available: %AvailableSegment{},
+          utilised: %UtilisedSegment{}
+        }
+
+  @derive {Jason.Encoder, only: Keyword.keys(@keys)}
+  defstruct @keys
+
+  def new(attributes) when is_map(attributes) do
+    struct(__MODULE__, %{
+      enabled: attributes["enabled"],
+      net: attributes["net"],
+      available: AvailableSegment.new(attributes["available"]),
+      utilised: UtilisedSegment.new(attributes["utilised"])
+    })
+  end
+
+  def new(_) do
+    struct(__MODULE__, %{})
+  end
+end

lib/kite_connect_ex/user/fund_and_margin/available_segment.ex

@@ -0,0 +1,37 @@
+defmodule KiteConnectEx.User.FundAndMargin.AvailableSegment do
+  @moduledoc """
+  Module to represent an available segment resource
+
+  - [Docs](https://kite.trade/docs/connect/v3/user/#funds-and-margins)
+  """
+
+  @keys [
+    adhoc_margin: nil,
+    cash: nil,
+    collateral: nil,
+    intraday_payin: nil
+  ]
+
+  @type t :: %__MODULE__{
+          adhoc_margin: Float.t(),
+          cash: Float.t(),
+          collateral: Float.t(),
+          intraday_payin: Float.t()
+        }
+
+  @derive {Jason.Encoder, only: Keyword.keys(@keys)}
+  defstruct @keys
+
+  def new(attributes) when is_map(attributes) do
+    struct(__MODULE__, %{
+      adhoc_margin: attributes["adhoc_margin"],
+      cash: attributes["cash"],
+      collateral: attributes["collateral"],
+      intraday_payin: attributes["intraday_payin"]
+    })
+  end
+
+  def new(_) do
+    struct(__MODULE__, %{})
+  end
+end

lib/kite_connect_ex/user/fund_and_margin/utilised_segment.ex

@@ -0,0 +1,52 @@
+defmodule KiteConnectEx.User.FundAndMargin.UtilisedSegment do
+  @moduledoc """
+  Module to represent an available segment resource
+
+  - [Docs](https://kite.trade/docs/connect/v3/user/#funds-and-margins)
+  """
+
+  @keys [
+    debits: nil,
+    exposure: nil,
+    m2m_realised: nil,
+    m2m_unrealised: nil,
+    option_premium: nil,
+    payout: nil,
+    span: nil,
+    holding_sales: nil,
+    turnover: nil
+  ]
+
+  @type t :: %__MODULE__{
+          debits: Float.t(),
+          exposure: Float.t(),
+          m2m_realised: Float.t(),
+          m2m_unrealised: Float.t(),
+          option_premium: Float.t(),
+          payout: Float.t(),
+          span: Float.t(),
+          holding_sales: Float.t(),
+          turnover: Float.t()
+        }
+
+  @derive {Jason.Encoder, only: Keyword.keys(@keys)}
+  defstruct @keys
+
+  def new(attributes) when is_map(attributes) do
+    struct(__MODULE__, %{
+      debits: attributes["debits"],
+      exposure: attributes["exposure"],
+      m2m_realised: attributes["m2m_realised"],
+      m2m_unrealised: attributes["m2m_unrealised"],
+      option_premium: attributes["option_premium"],
+      payout: attributes["payout"],
+      span: attributes["span"],
+      holding_sales: attributes["holding_sales"],
+      turnover: attributes["turnover"]
+    })
+  end
+
+  def new(_) do
+    struct(__MODULE__, %{})
+  end
+end

test/kite_connect_ex_test.exs

@@ -148,6 +148,90 @@ defmodule KiteConnectExTest do
     """
   end
 
+  describe "funds_and_margins/2" do
+    test "returns funds and margins for equity with valid response", %{bypass: bypass} do
+      Bypass.expect_once(bypass, "GET", "/user/margins/equity", fn conn ->
+        Plug.Conn.resp(conn, 201, funds_and_margins_response())
+      end)
+
+      assert KiteConnectEx.funds_and_margins("access-token", "equity") ==
+               {:ok,
+                %KiteConnectEx.User.FundAndMargin{
+                  available: %KiteConnectEx.User.FundAndMargin.AvailableSegment{
+                    adhoc_margin: 0,
+                    cash: 622.32,
+                    collateral: 0,
+                    intraday_payin: 0
+                  },
+                  enabled: true,
+                  net: 622.32,
+                  utilised: %KiteConnectEx.User.FundAndMargin.UtilisedSegment{
+                    debits: 0,
+                    exposure: 0,
+                    holding_sales: 0,
+                    m2m_realised: 0,
+                    m2m_unrealised: 0,
+                    option_premium: 0,
+                    payout: 0,
+                    span: 0,
+                    turnover: 0
+                  }
+                }}
+    end
+
+    test "returns error if API request fails", %{bypass: bypass} do
+      Bypass.expect_once(bypass, "GET", "/user/margins/equity", fn conn ->
+        Plug.Conn.resp(
+          conn,
+          403,
+          ~s<{"status": "error", "error_type": "TokenException", "message": "Invalid access_token"}>
+        )
+      end)
+
+      assert KiteConnectEx.funds_and_margins("access-token", "equity") ==
+               {:error,
+                %KiteConnectEx.Error{
+                  code: 403,
+                  error_type: "TokenException",
+                  message: "Invalid access_token"
+                }}
+    end
+
+    defp funds_and_margins_response do
+      """
+      {
+        "status": "success",
+        "data": {
+          "available": {
+            "adhoc_margin": 0,
+            "cash": 622.32,
+            "collateral": 0,
+            "intraday_payin": 0,
+            "live_balance": 622.32,
+            "opening_balance": 622.32
+          },
+          "enabled": true,
+          "net": 622.32,
+          "utilised": {
+            "debits": 0,
+            "delivery": 0,
+            "exposure": 0,
+            "holding_sales": 0,
+            "liquid_collateral": 0,
+            "m2m_realised": 0,
+            "m2m_unrealised": 0,
+            "option_premium": 0,
+            "payout": 0,
+            "span": 0,
+            "stock_collateral": 0,
+            "turnover": 0
+          }
+        }
+      }
+      """
+    end
+  end
+
   describe "holdings/1" do
     test "returns portfolio holdings with valid access_token", %{bypass: bypass} do
       Bypass.expect_once(bypass, "GET", "/portfolio/holdings", fn conn ->