From ae99052d34d5a061f5aaa6b4cb315ff3a3fd835a Mon Sep 17 00:00:00 2001
From: Fernando Canteiro <8915950+fcanteiro@users.noreply.github.com>
Date: Thu, 24 Oct 2024 17:01:48 +0100
Subject: [PATCH 1/5] changed deserialization to use string cast on response
 body

changed the deserialization process in the `Client` class to use `(string) $response->getBody()` instead of `$response->getBody()->getContents()`.

This change ensures that the response body is correctly read and deserialized, preventing potential issues with stream handling.
---
 src/Client.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Client.php b/src/Client.php
index debd270..c2776f4 100644
--- a/src/Client.php
+++ b/src/Client.php
@@ -350,7 +350,7 @@ public function request(
 
 
         $responseObject = $this->serializer->deserialize(
-            $response->getBody()->getContents(),
+            (string) $response->getBody(),
             $responsePayload,
             'json',
         );

From 30508abec2825e1f75e3cd4c2ba8b4c682c6ca3b Mon Sep 17 00:00:00 2001
From: Fernando Canteiro <8915950+fcanteiro@users.noreply.github.com>
Date: Fri, 25 Oct 2024 18:01:59 +0100
Subject: [PATCH 2/5] added support for List Earn Strategies endpoint

- Added response and entities for deserialization
- Implemented List Earn Strategies API call
---
 src/Client.php                                | 42 +++++++++++++++++
 src/Responses/EarnStrategiesResponse.php      | 13 +++++
 src/Responses/Entities/Earn/AprEstimate.php   | 14 ++++++
 src/Responses/Entities/Earn/AutoCompound.php  | 14 ++++++
 .../Entities/Earn/EarnStrategies.php          | 14 ++++++
 src/Responses/Entities/Earn/EarnStrategy.php  | 47 +++++++++++++++++++
 src/Responses/Entities/Earn/LockType.php      | 16 +++++++
 .../Entities/Earn/LockTypeBonded.php          | 32 +++++++++++++
 src/Responses/Entities/Earn/LockTypeFlex.php  |  5 ++
 .../Entities/Earn/LockTypeInstant.php         | 11 +++++
 src/Responses/Entities/Earn/YieldSource.php   | 11 +++++
 src/Serializer/EarnLockTypeHandler.php        | 41 ++++++++++++++++
 src/Serializer/SerializerFactory.php          |  1 +
 13 files changed, 261 insertions(+)
 create mode 100644 src/Responses/EarnStrategiesResponse.php
 create mode 100644 src/Responses/Entities/Earn/AprEstimate.php
 create mode 100644 src/Responses/Entities/Earn/AutoCompound.php
 create mode 100644 src/Responses/Entities/Earn/EarnStrategies.php
 create mode 100644 src/Responses/Entities/Earn/EarnStrategy.php
 create mode 100644 src/Responses/Entities/Earn/LockType.php
 create mode 100644 src/Responses/Entities/Earn/LockTypeBonded.php
 create mode 100644 src/Responses/Entities/Earn/LockTypeFlex.php
 create mode 100644 src/Responses/Entities/Earn/LockTypeInstant.php
 create mode 100644 src/Responses/Entities/Earn/YieldSource.php
 create mode 100644 src/Serializer/EarnLockTypeHandler.php

diff --git a/src/Client.php b/src/Client.php
index c2776f4..234b340 100644
--- a/src/Client.php
+++ b/src/Client.php
@@ -307,6 +307,48 @@ public function getWithdrawalInformation(string $asset, string $key, BigDecimal
         )->result;
     }
 
+    /**
+     * List earn strategies along with their parameters.
+     *
+     * Requires a valid API key but not specific permission is required.
+     *
+     * Returns only strategies that are available to the user based on geographic region.
+     *
+     * When the user does not meet the tier restriction:
+     * - `can_allocate` will be false
+     * - `allocation_restriction_info` indicates `Tier` as the restriction reason
+     *
+     * Earn products generally require Intermediate tier. Get your account verified to access earn.
+     *
+     * A note about `lock_type`:
+     * - `instant`: can be deallocated without an unbonding period. This is called flexible in the UI.
+     * - `bonded`: has an unbonding period. Deallocation will not happen until this period has passed.
+     * - `flex`: "Kraken rewards". This is earning on your spot balances where eligible. It's turned on account wide from the UI and you cannot manually allocate to these strategies.
+     *
+     * Paging isn't yet implemented, so the endpoint always returns all data in the first page.
+     *
+     * @param  string|null  $asset
+     * @param  array  $lockType
+     * @param  bool  $ascending
+     * @return EarnStrategies
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     * @see https://docs.kraken.com/api/docs/rest-api/list-strategies
+     */
+    public function getEarnStrategies(?string $asset = null, array $lockType = ['flex', 'bonded', 'instant'], bool $ascending = false): EarnStrategies
+    {
+        return $this->request(
+            method: 'private/Earn/Strategies',
+            responsePayload: EarnStrategiesResponse::class,
+            parameters: [
+                'asset' => $asset,
+                'lock_type' => $lockType,
+                'ascending' => $ascending ? 'true' : 'false',
+                // 'cursor' => '10', // not yet implemented
+                // 'limit' => 10, // not yet implemented
+            ],
+        )->result ?? null;
+    }
+
     /**
      * Make request
      *
diff --git a/src/Responses/EarnStrategiesResponse.php b/src/Responses/EarnStrategiesResponse.php
new file mode 100644
index 0000000..81b4493
--- /dev/null
+++ b/src/Responses/EarnStrategiesResponse.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Butschster\Kraken\Responses;
+
+use Butschster\Kraken\Responses\AbstractResponse;
+use Butschster\Kraken\Responses\Entities\Earn\EarnStrategies;
+use JMS\Serializer\Annotation\Type;
+
+class EarnStrategiesResponse extends AbstractResponse
+{
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\EarnStrategies")]
+    public ?EarnStrategies $result = null;
+}
diff --git a/src/Responses/Entities/Earn/AprEstimate.php b/src/Responses/Entities/Earn/AprEstimate.php
new file mode 100644
index 0000000..cf9d76a
--- /dev/null
+++ b/src/Responses/Entities/Earn/AprEstimate.php
@@ -0,0 +1,14 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn;
+
+use JMS\Serializer\Annotation\Type;
+
+class AprEstimate
+{
+    #[Type('string')]
+    public string $low;
+
+    #[Type('string')]
+    public string $high;
+}
diff --git a/src/Responses/Entities/Earn/AutoCompound.php b/src/Responses/Entities/Earn/AutoCompound.php
new file mode 100644
index 0000000..f622131
--- /dev/null
+++ b/src/Responses/Entities/Earn/AutoCompound.php
@@ -0,0 +1,14 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn;
+
+use JMS\Serializer\Annotation\Type;
+
+class AutoCompound
+{
+    #[Type('string')]
+    public string $type;
+
+    #[Type('bool|null')]
+    public ?bool $default = null;
+}
diff --git a/src/Responses/Entities/Earn/EarnStrategies.php b/src/Responses/Entities/Earn/EarnStrategies.php
new file mode 100644
index 0000000..8b18e22
--- /dev/null
+++ b/src/Responses/Entities/Earn/EarnStrategies.php
@@ -0,0 +1,14 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn;
+
+use JMS\Serializer\Annotation\Type;
+
+class EarnStrategies
+{
+    #[Type("array<Butschster\Kraken\Responses\Entities\Earn\EarnStrategy>")]
+    public array $items = [];
+
+    #[Type('string')]
+    public ?string $next_cursor = null;
+}
diff --git a/src/Responses/Entities/Earn/EarnStrategy.php b/src/Responses/Entities/Earn/EarnStrategy.php
new file mode 100644
index 0000000..8c9bd6b
--- /dev/null
+++ b/src/Responses/Entities/Earn/EarnStrategy.php
@@ -0,0 +1,47 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn;
+
+use JMS\Serializer\Annotation\Type;
+
+class EarnStrategy
+{
+    #[Type('string')]
+    public string $id;
+
+    #[Type('string')]
+    public string $asset;
+
+    #[Type("EarnLockType")]
+    public LockType $lock_type;
+
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\AprEstimate")]
+    public AprEstimate $apr_estimate;
+
+    #[Type('string')]
+    public ?string $user_cap;
+
+    #[Type('string')]
+    public ?string $user_min_allocation;
+
+    #[Type('string|int|float')]
+    public string|int|float $allocation_fee;
+
+    #[Type('string')]
+    public string $deallocation_fee;
+
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\AutoCompound")]
+    public AutoCompound $auto_compound;
+
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\YieldSource")]
+    public YieldSource $yield_source;
+
+    #[Type('bool')]
+    public bool $can_allocate;
+
+    #[Type('bool')]
+    public bool $can_deallocate;
+
+    #[Type('array')]
+    public array $allocation_restriction_info;
+}
diff --git a/src/Responses/Entities/Earn/LockType.php b/src/Responses/Entities/Earn/LockType.php
new file mode 100644
index 0000000..95db20b
--- /dev/null
+++ b/src/Responses/Entities/Earn/LockType.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn;
+
+use JMS\Serializer\Annotation\Type;
+
+class LockType
+{
+    #[Type('string')]
+    public string $type;
+
+    public function getType(): string
+    {
+        return $this->type;
+    }
+}
diff --git a/src/Responses/Entities/Earn/LockTypeBonded.php b/src/Responses/Entities/Earn/LockTypeBonded.php
new file mode 100644
index 0000000..32f86d5
--- /dev/null
+++ b/src/Responses/Entities/Earn/LockTypeBonded.php
@@ -0,0 +1,32 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn;
+
+use JMS\Serializer\Annotation\Type;
+
+class LockTypeBonded extends LockType
+{
+    #[Type('int')]
+    public int $payout_frequency;
+
+    #[Type('int')]
+    public int $bonding_period;
+
+    #[Type('bool')]
+    public bool $bonding_period_variable;
+
+    #[Type('bool')]
+    public bool $bonding_rewards;
+
+    #[Type('int')]
+    public int $exit_queue_period;
+
+    #[Type('int')]
+    public int $unbonding_period;
+
+    #[Type('bool')]
+    public bool $unbonding_period_variable;
+
+    #[Type('bool')]
+    public bool $unbonding_rewards;
+}
diff --git a/src/Responses/Entities/Earn/LockTypeFlex.php b/src/Responses/Entities/Earn/LockTypeFlex.php
new file mode 100644
index 0000000..002b1d4
--- /dev/null
+++ b/src/Responses/Entities/Earn/LockTypeFlex.php
@@ -0,0 +1,5 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn;
+
+class LockTypeFlex extends LockType {}
diff --git a/src/Responses/Entities/Earn/LockTypeInstant.php b/src/Responses/Entities/Earn/LockTypeInstant.php
new file mode 100644
index 0000000..2990678
--- /dev/null
+++ b/src/Responses/Entities/Earn/LockTypeInstant.php
@@ -0,0 +1,11 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn;
+
+use JMS\Serializer\Annotation\Type;
+
+class LockTypeInstant extends LockType
+{
+    #[Type('int')]
+    public int $payout_frequency;
+}
diff --git a/src/Responses/Entities/Earn/YieldSource.php b/src/Responses/Entities/Earn/YieldSource.php
new file mode 100644
index 0000000..defe47f
--- /dev/null
+++ b/src/Responses/Entities/Earn/YieldSource.php
@@ -0,0 +1,11 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn;
+
+use JMS\Serializer\Annotation\Type;
+
+class YieldSource
+{
+    #[Type('string')]
+    public string $type;
+}
diff --git a/src/Serializer/EarnLockTypeHandler.php b/src/Serializer/EarnLockTypeHandler.php
new file mode 100644
index 0000000..78adea1
--- /dev/null
+++ b/src/Serializer/EarnLockTypeHandler.php
@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Butschster\Kraken\Serializer;
+
+use Butschster\Kraken\Responses\Entities\Earn as Earn;
+use JMS\Serializer\Context;
+use JMS\Serializer\GraphNavigatorInterface;
+use JMS\Serializer\Handler\SubscribingHandlerInterface;
+use JMS\Serializer\JsonDeserializationVisitor;
+
+class EarnLockTypeHandler implements SubscribingHandlerInterface
+{
+    public static function getSubscribingMethods()
+    {
+        return [
+            [
+                'direction' => GraphNavigatorInterface::DIRECTION_DESERIALIZATION,
+                'format' => 'json',
+                'type' => 'EarnLockType',
+                'method' => 'deserialize',
+            ],
+        ];
+    }
+
+    public function deserialize(JsonDeserializationVisitor $visitor, $data, array $type, Context $context)
+    {
+        $navigator = $context->getNavigator();
+        switch ($data['type']) {
+            case 'instant':
+                return $navigator->accept($data, ['name' => Earn\LockTypeInstant::class], $context);
+            case 'flex':
+                return $navigator->accept($data, ['name' => Earn\LockTypeFlex::class], $context);
+            case 'bonded':
+                return $navigator->accept($data, ['name' => Earn\LockTypeBonded::class], $context);
+            default:
+                throw new \RuntimeException('Unknown lock type: '.$data['type']);
+        }
+    }
+}
diff --git a/src/Serializer/SerializerFactory.php b/src/Serializer/SerializerFactory.php
index 351dfed..701c1f9 100644
--- a/src/Serializer/SerializerFactory.php
+++ b/src/Serializer/SerializerFactory.php
@@ -23,6 +23,7 @@ public function build()
                 $registry->registerSubscribingHandler(new BigDecimalHandler());
                 $registry->registerSubscribingHandler(new TimestampHandler());
                 $registry->registerSubscribingHandler(new ComaSeparatedHandler());
+                $registry->registerSubscribingHandler(new EarnLockTypeHandler());
             });
 
         return $builder->build();

From 4844c5ebf95a8d3154aae40c5700b0c9867c8852 Mon Sep 17 00:00:00 2001
From: Fernando Canteiro <8915950+fcanteiro@users.noreply.github.com>
Date: Mon, 28 Oct 2024 10:33:26 +0000
Subject: [PATCH 3/5] Fixed missing imports

return is never null
---
 src/Client.php | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/Client.php b/src/Client.php
index 234b340..d08ff91 100644
--- a/src/Client.php
+++ b/src/Client.php
@@ -15,9 +15,11 @@
     ClosedOrdersResponse,
     DepositAddressesResponse,
     DepositMethodsResponse,
+    EarnStrategiesResponse,
     Entities\AddOrder\OrderAdded,
     Entities\CancelOrdersAfterTimeout,
     Entities\DepositMethods,
+    Entities\Earn\EarnStrategies,
     Entities\Orders\ClosedOrders,
     Entities\ServerTime,
     Entities\SystemStatus,
@@ -346,7 +348,7 @@ public function getEarnStrategies(?string $asset = null, array $lockType = ['fle
                 // 'cursor' => '10', // not yet implemented
                 // 'limit' => 10, // not yet implemented
             ],
-        )->result ?? null;
+        )->result;
     }
 
     /**

From 33e20efd9e827c72346352a09ba9d300850a3ed4 Mon Sep 17 00:00:00 2001
From: Fernando Canteiro <8915950+fcanteiro@users.noreply.github.com>
Date: Mon, 28 Oct 2024 11:34:31 +0000
Subject: [PATCH 4/5] added support for List Earn Allocations endpoint

- Added EarnAllocationResponse, EarnAllocations, and related entities for deserialization
- Implemented getEarnAllocations method in Client class
---
 src/Client.php                                | 51 +++++++++++++++++++
 src/Responses/EarnAllocationsResponse.php     | 12 +++++
 .../Entities/Earn/Allocation/Allocation.php   | 23 +++++++++
 .../Entities/Earn/Allocation/Allocations.php  | 24 +++++++++
 .../Earn/Allocation/AmountAllocated.php       | 11 ++++
 .../Entities/Earn/Allocation/Payout.php       | 21 ++++++++
 .../Entities/Earn/Allocation/Reward.php       | 15 ++++++
 .../Entities/Earn/Allocation/Total.php        | 15 ++++++
 .../Earn/Allocation/TotalRewarded.php         | 15 ++++++
 9 files changed, 187 insertions(+)
 create mode 100644 src/Responses/EarnAllocationsResponse.php
 create mode 100644 src/Responses/Entities/Earn/Allocation/Allocation.php
 create mode 100644 src/Responses/Entities/Earn/Allocation/Allocations.php
 create mode 100644 src/Responses/Entities/Earn/Allocation/AmountAllocated.php
 create mode 100644 src/Responses/Entities/Earn/Allocation/Payout.php
 create mode 100644 src/Responses/Entities/Earn/Allocation/Reward.php
 create mode 100644 src/Responses/Entities/Earn/Allocation/Total.php
 create mode 100644 src/Responses/Entities/Earn/Allocation/TotalRewarded.php

diff --git a/src/Client.php b/src/Client.php
index d08ff91..4b04481 100644
--- a/src/Client.php
+++ b/src/Client.php
@@ -15,10 +15,12 @@
     ClosedOrdersResponse,
     DepositAddressesResponse,
     DepositMethodsResponse,
+    EarnAllocationsResponse,
     EarnStrategiesResponse,
     Entities\AddOrder\OrderAdded,
     Entities\CancelOrdersAfterTimeout,
     Entities\DepositMethods,
+    Entities\Earn\Allocation\Allocations,
     Entities\Earn\EarnStrategies,
     Entities\Orders\ClosedOrders,
     Entities\ServerTime,
@@ -351,6 +353,55 @@ public function getEarnStrategies(?string $asset = null, array $lockType = ['fle
         )->result;
     }
 
+    /**
+     * List all allocations for the user.
+     *
+     * Requires the `Query Funds` API key permission.
+     *
+     * By default, all allocations are returned, even for strategies that have been used in the past and have zero balance now.
+     * This allows the user to see how much was earned with a given strategy in the past. The `hide_zero_allocations` parameter
+     * can be used to remove zero balance entries from the output. Paging hasn't been implemented for this method as we don't
+     * expect the result for a particular user to be overwhelmingly large.
+     *
+     * All amounts in the output can be denominated in a currency of the user's choice (the `converted_asset` parameter).
+     *
+     * Information about when the next reward will be paid to the client is also provided in the output.
+     *
+     * Allocated funds can be in up to 4 states:
+     * - bonding
+     * - allocated
+     * - exit_queue (ETH only)
+     * - unbonding
+     *
+     * Any funds in `total` not in `bonding`/`unbonding` are simply allocated and earning rewards. Depending on the strategy, funds
+     * in the other 3 states can also be earning rewards. Consult the output of `/Earn/Strategies` to know whether `bonding`/`unbonding`
+     * earn rewards. `ETH` in `exit_queue` still earns rewards.
+     *
+     * Note that for `ETH`, when the funds are in the `exit_queue` state, the `expires` time given is the time when the funds will have
+     * finished unbonding, not when they go from exit queue to unbonding.
+     *
+     * (Un)bonding time estimate can be inaccurate right after having (de)allocated the funds. Wait 1-2 minutes after (de)allocating
+     * to get an accurate result.
+     *
+     * @param  string  $convertedAsset The currency to which amounts should be converted. Default is 'USD'.
+     * @param  bool  $hideZeroAllocations Whether to hide allocations with zero balance. Default is false.
+     * @param  bool  $ascending Whether to sort the results in ascending order. Default is false.
+     * @return Allocations The list of allocations.
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     */
+    public function getEarnAllocations(string $convertedAsset = 'USD', bool $hideZeroAllocations = false, bool $ascending = false): Allocations
+    {
+        return $this->request(
+            method: 'private/Earn/Allocations',
+            responsePayload: EarnAllocationsResponse::class,
+            parameters: [
+                'ascending' => $ascending ? 'true' : 'false',
+                'converted_asset' => $convertedAsset,
+                'hide_zero_allocations' => $hideZeroAllocations ? 'true' : 'false',
+            ]
+        )->result;
+    }
+
     /**
      * Make request
      *
diff --git a/src/Responses/EarnAllocationsResponse.php b/src/Responses/EarnAllocationsResponse.php
new file mode 100644
index 0000000..5a4728f
--- /dev/null
+++ b/src/Responses/EarnAllocationsResponse.php
@@ -0,0 +1,12 @@
+<?php
+
+namespace Butschster\Kraken\Responses;
+
+use Butschster\Kraken\Responses\Entities\Earn\Allocation\Allocations;
+use JMS\Serializer\Annotation\Type;
+
+class EarnAllocationsResponse extends AbstractResponse
+{
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\Allocation\Allocations")]
+    public ?Allocations $result = null;
+}
diff --git a/src/Responses/Entities/Earn/Allocation/Allocation.php b/src/Responses/Entities/Earn/Allocation/Allocation.php
new file mode 100644
index 0000000..4f445b8
--- /dev/null
+++ b/src/Responses/Entities/Earn/Allocation/Allocation.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn\Allocation;
+
+use JMS\Serializer\Annotation\Type;
+
+class Allocation
+{
+    #[Type('string')]
+    public string $strategy_id;
+
+    #[Type('string')]
+    public string $native_asset;
+
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\Allocation\AmountAllocated")]
+    public AmountAllocated $amount_allocated;
+
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\Allocation\TotalRewarded")]
+    public TotalRewarded $total_rewarded;
+
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\Allocation\Payout")]
+    public Payout $payout;
+}
diff --git a/src/Responses/Entities/Earn/Allocation/Allocations.php b/src/Responses/Entities/Earn/Allocation/Allocations.php
new file mode 100644
index 0000000..d4f0028
--- /dev/null
+++ b/src/Responses/Entities/Earn/Allocation/Allocations.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn\Allocation;
+
+use Brick\Math\BigDecimal;
+use JMS\Serializer\Annotation\Type;
+
+class Allocations
+{
+    #[Type('string')]
+    public string $converted_asset;
+
+    #[Type(\Brick\Math\BigDecimal::class)]
+    public BigDecimal $total_allocated;
+
+    #[Type(\Brick\Math\BigDecimal::class)]
+    public BigDecimal $total_rewarded;
+
+    #[Type('string')]
+    public ?string $next_cursor = null;
+
+    #[Type("array<Butschster\Kraken\Responses\Entities\Earn\Allocation\Allocation>")]
+    public array $items = [];
+}
diff --git a/src/Responses/Entities/Earn/Allocation/AmountAllocated.php b/src/Responses/Entities/Earn/Allocation/AmountAllocated.php
new file mode 100644
index 0000000..0dd63b1
--- /dev/null
+++ b/src/Responses/Entities/Earn/Allocation/AmountAllocated.php
@@ -0,0 +1,11 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn\Allocation;
+
+use JMS\Serializer\Annotation\Type;
+
+class AmountAllocated
+{
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\Allocation\Total")]
+    public Total $total;
+}
diff --git a/src/Responses/Entities/Earn/Allocation/Payout.php b/src/Responses/Entities/Earn/Allocation/Payout.php
new file mode 100644
index 0000000..2358376
--- /dev/null
+++ b/src/Responses/Entities/Earn/Allocation/Payout.php
@@ -0,0 +1,21 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn\Allocation;
+
+use Carbon\Carbon;
+use JMS\Serializer\Annotation\Type;
+
+class Payout
+{
+    #[Type('Timestamp')]
+    public Carbon $period_start;
+
+    #[Type('Timestamp')]
+    public Carbon $period_end;
+
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\Allocation\Reward")]
+    public Reward $accumulated_reward;
+
+    #[Type("Butschster\Kraken\Responses\Entities\Earn\Allocation\Reward")]
+    public Reward $estimated_reward;
+}
diff --git a/src/Responses/Entities/Earn/Allocation/Reward.php b/src/Responses/Entities/Earn/Allocation/Reward.php
new file mode 100644
index 0000000..33b41a1
--- /dev/null
+++ b/src/Responses/Entities/Earn/Allocation/Reward.php
@@ -0,0 +1,15 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn\Allocation;
+
+use Brick\Math\BigDecimal;
+use JMS\Serializer\Annotation\Type;
+
+class Reward
+{
+    #[Type(\Brick\Math\BigDecimal::class)]
+    public BigDecimal $native;
+
+    #[Type(\Brick\Math\BigDecimal::class)]
+    public BigDecimal $converted;
+}
diff --git a/src/Responses/Entities/Earn/Allocation/Total.php b/src/Responses/Entities/Earn/Allocation/Total.php
new file mode 100644
index 0000000..f69270f
--- /dev/null
+++ b/src/Responses/Entities/Earn/Allocation/Total.php
@@ -0,0 +1,15 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn\Allocation;
+
+use Brick\Math\BigDecimal;
+use JMS\Serializer\Annotation\Type;
+
+class Total
+{
+    #[Type(\Brick\Math\BigDecimal::class)]
+    public BigDecimal $native;
+
+    #[Type(\Brick\Math\BigDecimal::class)]
+    public BigDecimal $converted;
+}
diff --git a/src/Responses/Entities/Earn/Allocation/TotalRewarded.php b/src/Responses/Entities/Earn/Allocation/TotalRewarded.php
new file mode 100644
index 0000000..197c7cf
--- /dev/null
+++ b/src/Responses/Entities/Earn/Allocation/TotalRewarded.php
@@ -0,0 +1,15 @@
+<?php
+
+namespace Butschster\Kraken\Responses\Entities\Earn\Allocation;
+
+use Brick\Math\BigDecimal;
+use JMS\Serializer\Annotation\Type;
+
+class TotalRewarded
+{
+    #[Type(\Brick\Math\BigDecimal::class)]
+    public BigDecimal $native;
+
+    #[Type(\Brick\Math\BigDecimal::class)]
+    public BigDecimal $converted;
+}

From ba661fb5221368158675ec9c7d88300a11b2083c Mon Sep 17 00:00:00 2001
From: Fernando Canteiro <8915950+fcanteiro@users.noreply.github.com>
Date: Mon, 28 Oct 2024 17:04:09 +0000
Subject: [PATCH 5/5] added support to Allocate and Deallocate funds

- moved PHPDocs to client Interface
---
 src/Client.php                          |  87 +++++------------
 src/Contracts/Client.php                | 122 ++++++++++++++++++++++++
 src/Contracts/EarnAllocationRequest.php |  19 ++++
 src/Requests/EarnAllocationRequest.php  |  43 +++++++++
 src/Responses/BoolStatusResponse.php    |  11 +++
 5 files changed, 219 insertions(+), 63 deletions(-)
 create mode 100644 src/Contracts/EarnAllocationRequest.php
 create mode 100644 src/Requests/EarnAllocationRequest.php
 create mode 100644 src/Responses/BoolStatusResponse.php

diff --git a/src/Client.php b/src/Client.php
index 4b04481..b07c4da 100644
--- a/src/Client.php
+++ b/src/Client.php
@@ -10,6 +10,7 @@
 use Butschster\Kraken\Responses\{AccountBalanceResponse,
     AddOrderResponse,
     AssetInfoResponse,
+    BoolStatusResponse,
     CancelOrderResponse,
     CancelOrdersAfterTimeoutResponse,
     ClosedOrdersResponse,
@@ -42,6 +43,7 @@
 use Butschster\Kraken\ValueObjects\{
     AssetClass, AssetPair, TradableInfo
 };
+use Butschster\Kraken\Requests\EarnAllocationRequest;
 use DateTimeInterface;
 use Illuminate\Support\Str;
 use JMS\Serializer\SerializerInterface;
@@ -311,33 +313,6 @@ public function getWithdrawalInformation(string $asset, string $key, BigDecimal
         )->result;
     }
 
-    /**
-     * List earn strategies along with their parameters.
-     *
-     * Requires a valid API key but not specific permission is required.
-     *
-     * Returns only strategies that are available to the user based on geographic region.
-     *
-     * When the user does not meet the tier restriction:
-     * - `can_allocate` will be false
-     * - `allocation_restriction_info` indicates `Tier` as the restriction reason
-     *
-     * Earn products generally require Intermediate tier. Get your account verified to access earn.
-     *
-     * A note about `lock_type`:
-     * - `instant`: can be deallocated without an unbonding period. This is called flexible in the UI.
-     * - `bonded`: has an unbonding period. Deallocation will not happen until this period has passed.
-     * - `flex`: "Kraken rewards". This is earning on your spot balances where eligible. It's turned on account wide from the UI and you cannot manually allocate to these strategies.
-     *
-     * Paging isn't yet implemented, so the endpoint always returns all data in the first page.
-     *
-     * @param  string|null  $asset
-     * @param  array  $lockType
-     * @param  bool  $ascending
-     * @return EarnStrategies
-     * @throws \GuzzleHttp\Exception\GuzzleException
-     * @see https://docs.kraken.com/api/docs/rest-api/list-strategies
-     */
     public function getEarnStrategies(?string $asset = null, array $lockType = ['flex', 'bonded', 'instant'], bool $ascending = false): EarnStrategies
     {
         return $this->request(
@@ -353,42 +328,6 @@ public function getEarnStrategies(?string $asset = null, array $lockType = ['fle
         )->result;
     }
 
-    /**
-     * List all allocations for the user.
-     *
-     * Requires the `Query Funds` API key permission.
-     *
-     * By default, all allocations are returned, even for strategies that have been used in the past and have zero balance now.
-     * This allows the user to see how much was earned with a given strategy in the past. The `hide_zero_allocations` parameter
-     * can be used to remove zero balance entries from the output. Paging hasn't been implemented for this method as we don't
-     * expect the result for a particular user to be overwhelmingly large.
-     *
-     * All amounts in the output can be denominated in a currency of the user's choice (the `converted_asset` parameter).
-     *
-     * Information about when the next reward will be paid to the client is also provided in the output.
-     *
-     * Allocated funds can be in up to 4 states:
-     * - bonding
-     * - allocated
-     * - exit_queue (ETH only)
-     * - unbonding
-     *
-     * Any funds in `total` not in `bonding`/`unbonding` are simply allocated and earning rewards. Depending on the strategy, funds
-     * in the other 3 states can also be earning rewards. Consult the output of `/Earn/Strategies` to know whether `bonding`/`unbonding`
-     * earn rewards. `ETH` in `exit_queue` still earns rewards.
-     *
-     * Note that for `ETH`, when the funds are in the `exit_queue` state, the `expires` time given is the time when the funds will have
-     * finished unbonding, not when they go from exit queue to unbonding.
-     *
-     * (Un)bonding time estimate can be inaccurate right after having (de)allocated the funds. Wait 1-2 minutes after (de)allocating
-     * to get an accurate result.
-     *
-     * @param  string  $convertedAsset The currency to which amounts should be converted. Default is 'USD'.
-     * @param  bool  $hideZeroAllocations Whether to hide allocations with zero balance. Default is false.
-     * @param  bool  $ascending Whether to sort the results in ascending order. Default is false.
-     * @return Allocations The list of allocations.
-     * @throws \GuzzleHttp\Exception\GuzzleException
-     */
     public function getEarnAllocations(string $convertedAsset = 'USD', bool $hideZeroAllocations = false, bool $ascending = false): Allocations
     {
         return $this->request(
@@ -402,6 +341,28 @@ public function getEarnAllocations(string $convertedAsset = 'USD', bool $hideZer
         )->result;
     }
 
+    public function allocateEarnFunds(BigDecimal $amount, string $strategyId): bool
+    {
+        $request = new EarnAllocationRequest($amount, $strategyId);
+
+        return $this->request(
+            method: 'private/Earn/Allocate',
+            responsePayload: BoolStatusResponse::class,
+            parameters: $request->toArray(),
+        )->result;
+    }
+
+    public function deallocateEarnFunds(BigDecimal $amount, string $strategyId): bool
+    {
+        $request = new EarnAllocationRequest($amount, $strategyId);
+
+        return $this->request(
+            method: 'private/Earn/Deallocate',
+            responsePayload: BoolStatusResponse::class,
+            parameters: $request->toArray(),
+        )->result;
+    }
+
     /**
      * Make request
      *
diff --git a/src/Contracts/Client.php b/src/Contracts/Client.php
index 0eee94a..950fe4c 100644
--- a/src/Contracts/Client.php
+++ b/src/Contracts/Client.php
@@ -9,6 +9,8 @@
 use Butschster\Kraken\Responses\Entities\CancelOrdersAfterTimeout;
 use Butschster\Kraken\Responses\Entities\DepositAddresses;
 use Butschster\Kraken\Responses\Entities\DepositMethods;
+use Butschster\Kraken\Responses\Entities\Earn\Allocation\Allocations;
+use Butschster\Kraken\Responses\Entities\Earn\EarnStrategies;
 use Butschster\Kraken\Responses\Entities\OrderBook\Orders;
 use Butschster\Kraken\Responses\Entities\Orders\ClosedOrders;
 use Butschster\Kraken\Responses\Entities\Orders\Order;
@@ -23,6 +25,7 @@
 use Butschster\Kraken\ValueObjects\AssetPair;
 use Butschster\Kraken\ValueObjects\TradableInfo;
 use DateTimeInterface;
+use GuzzleHttp\Exception\GuzzleException;
 
 interface Client
 {
@@ -208,4 +211,123 @@ public function getDepositAddresses(string $asset, string $method, bool $new = f
      * @return WithdrawalInformation
      */
     public function getWithdrawalInformation(string $asset, string $key, BigDecimal $amount): WithdrawalInformation;
+
+    /**
+     * List earn strategies along with their parameters.
+     *
+     * Requires a valid API key but not specific permission is required.
+     *
+     * Returns only strategies that are available to the user based on geographic region.
+     *
+     * When the user does not meet the tier restriction:
+     * - `can_allocate` will be false
+     * - `allocation_restriction_info` indicates `Tier` as the restriction reason
+     *
+     * Earn products generally require Intermediate tier. Get your account verified to access earn.
+     *
+     * A note about `lock_type`:
+     * - `instant`: can be deallocated without an unbonding period. This is called flexible in the UI.
+     * - `bonded`: has an unbonding period. Deallocation will not happen until this period has passed.
+     * - `flex`: "Kraken rewards". This is earning on your spot balances where eligible. It's turned on account wide from the UI and you cannot manually allocate to these strategies.
+     *
+     * Paging isn't yet implemented, so the endpoint always returns all data in the first page.
+     *
+     * @see https://docs.kraken.com/api/docs/rest-api/list-strategies
+     * @param  string|null  $asset
+     * @param  array  $lockType
+     * @param  bool  $ascending
+     * @return EarnStrategies
+     */
+    public function getEarnStrategies(?string $asset = null, array $lockType = ['flex', 'bonded', 'instant'], bool $ascending = false): EarnStrategies;
+
+    /**
+     * List all allocations for the user.
+     *
+     * Requires the `Query Funds` API key permission.
+     *
+     * By default, all allocations are returned, even for strategies that have been used in the past and have zero balance now.
+     * This allows the user to see how much was earned with a given strategy in the past. The `hide_zero_allocations` parameter
+     * can be used to remove zero balance entries from the output. Paging hasn't been implemented for this method as we don't
+     * expect the result for a particular user to be overwhelmingly large.
+     *
+     * All amounts in the output can be denominated in a currency of the user's choice (the `converted_asset` parameter).
+     *
+     * Information about when the next reward will be paid to the client is also provided in the output.
+     *
+     * Allocated funds can be in up to 4 states:
+     * - bonding
+     * - allocated
+     * - exit_queue (ETH only)
+     * - unbonding
+     *
+     * Any funds in `total` not in `bonding`/`unbonding` are simply allocated and earning rewards. Depending on the strategy, funds
+     * in the other 3 states can also be earning rewards. Consult the output of `/Earn/Strategies` to know whether `bonding`/`unbonding`
+     * earn rewards. `ETH` in `exit_queue` still earns rewards.
+     *
+     * Note that for `ETH`, when the funds are in the `exit_queue` state, the `expires` time given is the time when the funds will have
+     * finished unbonding, not when they go from exit queue to unbonding.
+     *
+     * (Un)bonding time estimate can be inaccurate right after having (de)allocated the funds. Wait 1-2 minutes after (de)allocating
+     * to get an accurate result.
+     *
+     * @see https://docs.kraken.com/api/docs/rest-api/list-allocations
+     * @param  string  $convertedAsset The currency to which amounts should be converted. Default is 'USD'.
+     * @param  bool  $hideZeroAllocations Whether to hide allocations with zero balance. Default is false.
+     * @param  bool  $ascending Whether to sort the results in ascending order. Default is false.
+     * @return Allocations The list of allocations.
+     */
+    public function getEarnAllocations(string $convertedAsset = 'USD', bool $hideZeroAllocations = false, bool $ascending = false): Allocations;
+
+    /**
+     * Allocate funds to the Strategy.
+     *
+     * Requires the `Earn Funds` API key permission. The amount must always be defined.
+     *
+     * This method is asynchronous. A couple of preflight checks are performed synchronously on behalf of the
+     * method before it is dispatched further. The client is required to poll the result using the
+     * `/0/private/Earn/AllocateStatus` endpoint.
+     *
+     * There can be only one (de)allocation request in progress for a given user and strategy at any time. While the operation is in progress:
+     * - `pending` attribute in `/Earn/Allocations` response for the strategy indicates that funds are being allocated,
+     * - `pending` attribute in `/Earn/AllocateStatus` response will be true.
+     *
+     * Following specific errors within `Earnings` class can be returned by this method:
+     * - Minimum allocation: `EEarnings:Below min:(De)allocation operation amount less than minimum`
+     * - Allocation in progress: `EEarnings:Busy:Another (de)allocation for the same strategy is in progress`
+     * - Service temporarily unavailable: `EEarnings:Busy`. Try again in a few minutes.
+     * - User tier verification: `EEarnings:Permission denied:The user's tier is not high enough`
+     * - Strategy not found: `EGeneral:Invalid arguments:Invalid strategy ID`
+     *
+     * @see https://docs.kraken.com/api/docs/rest-api/allocate-strategy
+     * @param  BigDecimal  $amount
+     * @param  string  $strategyId
+     * @return bool
+     */
+    public function allocateEarnFunds(BigDecimal $amount, string $strategyId): bool;
+
+
+    /**
+     * Deallocate funds from a strategy.
+     *
+     * Requires the `Earn Funds` API key permission. The amount must always be defined.
+     *
+     * This method is asynchronous. A couple of preflight checks are performed synchronously on behalf of the
+     * method before it is dispatched further. If the method returns HTTP 202 code, the client is required to poll
+     * the result using the `/Earn/DeallocateStatus` endpoint.
+     *
+     * There can be only one (de)allocation request in progress for a given user and strategy. While the operation is in progress:
+     * - `pending` attribute in `Allocations` response for the strategy will hold the amount that is being deallocated (negative amount)
+     * - `pending` attribute in `DeallocateStatus` response will be true.
+     *
+     * Following specific errors within `Earnings` class can be returned by this method:
+     * - Minimum allocation: `EEarnings:Below min:(De)allocation operation amount less than minimum allowed`
+     * - Allocation in progress: `EEarnings:Busy:Another (de)allocation for the same strategy is in progress`
+     * - Strategy not found: `EGeneral:Invalid arguments:Invalid strategy ID`
+     *
+     * @see https://docs.kraken.com/api/docs/rest-api/deallocate-strategy
+     * @param  BigDecimal  $amount
+     * @param  string  $strategyId
+     * @return bool
+     */
+    public function deallocateEarnFunds(BigDecimal $amount, string $strategyId): bool;
 }
diff --git a/src/Contracts/EarnAllocationRequest.php b/src/Contracts/EarnAllocationRequest.php
new file mode 100644
index 0000000..e4faae5
--- /dev/null
+++ b/src/Contracts/EarnAllocationRequest.php
@@ -0,0 +1,19 @@
+<?php
+
+namespace Butschster\Kraken\Contracts;
+
+use Brick\Math\BigDecimal;
+use Illuminate\Contracts\Support\Arrayable;
+
+interface EarnAllocationRequest extends Arrayable
+{
+    /**
+     * The amount to allocate.
+     */
+    public function amount(): ?BigDecimal;
+
+    /**
+     * A unique identifier of the chosen earn strategy, as returned from `/0/private/Earn/Strategies`.
+     */
+    public function strategy_id(): string;
+}
diff --git a/src/Requests/EarnAllocationRequest.php b/src/Requests/EarnAllocationRequest.php
new file mode 100644
index 0000000..877660b
--- /dev/null
+++ b/src/Requests/EarnAllocationRequest.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace Butschster\Kraken\Requests;
+
+use Brick\Math\BigDecimal;
+
+class EarnAllocationRequest implements \Butschster\Kraken\Contracts\EarnAllocationRequest
+{
+    public function __construct(
+        private ?BigDecimal $amount = null, private ?string $strategy_id = null) {}
+
+    public function setAmount(?BigDecimal $amount): self
+    {
+        $this->amount = $amount;
+
+        return $this;
+    }
+
+    public function setStrategyId(?string $strategy_id): self
+    {
+        $this->strategy_id = $strategy_id;
+
+        return $this;
+    }
+
+    public function amount(): ?BigDecimal
+    {
+        return $this->amount;
+    }
+
+    public function strategy_id(): string
+    {
+        return $this->strategy_id;
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'amount' => (string) $this->amount(),
+            'strategy_id' => $this->strategy_id(),
+        ];
+    }
+}
diff --git a/src/Responses/BoolStatusResponse.php b/src/Responses/BoolStatusResponse.php
new file mode 100644
index 0000000..ab4828d
--- /dev/null
+++ b/src/Responses/BoolStatusResponse.php
@@ -0,0 +1,11 @@
+<?php
+
+namespace Butschster\Kraken\Responses;
+
+use JMS\Serializer\Annotation\Type;
+
+class BoolStatusResponse extends AbstractResponse
+{
+    #[Type('bool')]
+    public bool $result;
+}