feat: sui staking-api docs

docs/staking-api/sui/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Sui",
+  "position": 8,
+  "link": {
+    "type": "doc",
+    "id": "staking-api/sui/index"
+  }
+}

docs/staking-api/sui/index.md

@@ -0,0 +1,23 @@
+---
+title: Sui
+---
+
+# Sui
+
+This section covers Sui staking integrations using the Stakely Staking API. It includes Sui-specific notes, transaction signing examples, and native staking flows supported by Stakely.
+
+## Useful links
+
+- Stakely, Sui (SUI) staking overview: https://stakely.io/staking/sui-staking
+- Official documentation: https://docs.sui.io
+
+## What you will find in this section
+
+- **Signing transactions**: how to sign Sui transactions returned by the crafting endpoints, with examples for common signing setups.
+- **Native staking**: end-to-end flows and endpoints for staking, unstaking, and querying staked balances on Sui.
+
+## Notes
+
+- Sui integrations require specifying the correct `X-NETWORK` for the target network. The API provides a dedicated endpoint to list all available Sui networks and their corresponding `X-NETWORK` values.
+- All staking operations are executed on-chain. Stakely prepares the transaction payloads, while signing is performed by your application using your preferred signing method.
+- Sui staking responses may include values in both `SUI` and `MIST` units (`1 SUI = 1,000,000,000 MIST`).

docs/staking-api/sui/native-staking/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Native Staking",
+  "position": 3,
+  "link": {
+    "type": "doc",
+    "id": "staking-api/sui/native-staking/index"
+  }
+}

docs/staking-api/sui/native-staking/endpoints.md

@@ -0,0 +1,194 @@
+---
+sidebar_position: 3
+---
+# Endpoints
+
+import StakingOpenApiLink from '@site/src/components/StakingOpenApiLink';
+
+## API Usage
+Once you already have access to the Staking API with a validated user and existing apikeys you can start using this service.
+
+### API Reference docs
+
+:::tip
+
+You can check the **Staking API Reference** here:
+- Rendered <a href="/staking-api/api-reference" target="_blank" rel="noopener noreferrer">doc page</a>.
+- <StakingOpenApiLink />
+:::
+
+## Authentication
+
+In order to use staking api related endpoints you need to include your **API KEY**.
+
+:::tip
+
+**Heads up!**
+To obtain a valid API key required for authentication, please refer to the [Authentication > Auth](/staking-api/authentication#auth) section of the documentation.
+
+:::
+
+**Header:**
+
+| Name        | Description | Example value | Required |
+|-------------|-------------|---------------|----------|
+| `X-API-KEY` | Your api key value | `<API_KEY_VALUE>` | ✅ |
+| `X-NETWORK` | Blockchain network identifier | `mainnet` | ⚪ |
+
+### X-NETWORK header
+
+Use the `X-NETWORK` header to select the Sui network.
+
+::::info
+If you omit the header the API falls back to the default Sui network configured for your account.
+::::
+
+____
+
+### List available networks
+
+Use this helper endpoint to obtain the list of Sui staking networks currently enabled for your API key.
+
+- Endpoint: <a href="/staking-api/api-reference#tag/sui/GET/api/v1/sui/native/networks" target="_blank" rel="noopener noreferrer"><code>/api/v1/sui/native/networks</code></a>
+- Method: `GET`
+
+Response payload fields:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Internal blockchain entry name |
+| `type` | Blockchain type string (always `SUI`) |
+| `chain_id` | Chain identifier |
+| `is_default` | `true` when this network is used as fallback |
+
+____
+
+### Stake action
+
+Craft an unsigned stake transaction:
+
+- Endpoint: <a href="/staking-api/api-reference#tag/sui/POST/api/v1/sui/native/action/stake" target="_blank" rel="noopener noreferrer"><code>/api/v1/sui/native/action/stake</code></a>
+- Method: `POST`
+
+#### Description
+
+This endpoint crafts an unsigned stake transaction ready to be signed.
+
+#### Request body parameters
+
+<a href="/staking-api/api-reference#model/SuiStakeActionDto" target="_blank" rel="noopener noreferrer"><code>SuiStakeActionDto</code></a>
+
+- `wallet_address` (required): Wallet address of the user that will perform the staking action.
+- `validator_address` (optional): Validator address to stake to. If omitted, defaults to configured validator.
+- `amount` (required): Amount of SUI to stake (minimum 1 SUI, up to 9 decimals).
+
+#### Returned
+
+<a href="/staking-api/api-reference#model/SuiStakeActionResponseDto" target="_blank" rel="noopener noreferrer"><code>SuiStakeActionResponseDto</code></a>
+
+- `unsigned_tx_b64`: Unsigned transaction bytes encoded as base64.
+
+____
+
+### Unstake action
+
+Craft an unsigned unstake transaction:
+
+- Endpoint: <a href="/staking-api/api-reference#tag/sui/POST/api/v1/sui/native/action/unstake" target="_blank" rel="noopener noreferrer"><code>/api/v1/sui/native/action/unstake</code></a>
+- Method: `POST`
+
+#### Description
+
+This endpoint crafts an unsigned unstake transaction ready to be signed.
+
+#### Request body parameters
+
+<a href="/staking-api/api-reference#model/SuiUnstakeActionDto" target="_blank" rel="noopener noreferrer"><code>SuiUnstakeActionDto</code></a>
+
+- `wallet_address` (required): Wallet address of the user that will perform the unstaking action.
+- `staked_sui_object_id` (required): Object ID of the `StakedSui` object to withdraw.
+
+#### Returned
+
+<a href="/staking-api/api-reference#model/SuiStakeActionResponseDto" target="_blank" rel="noopener noreferrer"><code>SuiStakeActionResponseDto</code></a>
+
+- `unsigned_tx_b64`: Unsigned transaction bytes encoded as base64.
+
+____
+
+### Prepare action
+
+Gathers signatures and unsigned transaction:
+
+- Endpoint: <a href="/staking-api/api-reference#tag/sui/POST/api/v1/sui/native/action/prepare" target="_blank" rel="noopener noreferrer"><code>/api/v1/sui/native/action/prepare</code></a>
+- Method: `POST`
+
+#### Description
+
+Prepare a signed transaction by combining the unsigned transaction bytes and signatures into a single payload.
+
+#### Request body parameters
+
+<a href="/staking-api/api-reference#model/SuiPrepareActionDto" target="_blank" rel="noopener noreferrer"><code>SuiPrepareActionDto</code></a>
+
+- `unsigned_tx_b64`: Unsigned transaction bytes in base64.
+- `signatures`: Array of base64-encoded signatures.
+
+#### Returned
+
+<a href="/staking-api/api-reference#model/SuiPrepareActionResponseDto" target="_blank" rel="noopener noreferrer"><code>SuiPrepareActionResponseDto</code></a>
+
+____
+
+### Broadcast action
+
+Broadcast a signed transaction:
+
+- Endpoint: <a href="/staking-api/api-reference#tag/sui/POST/api/v1/sui/native/action/broadcast" target="_blank" rel="noopener noreferrer"><code>/api/v1/sui/native/action/broadcast</code></a>
+- Method: `POST`
+
+#### Description
+
+Broadcast a signed Sui transaction.
+
+#### Request body parameters
+
+<a href="/staking-api/api-reference#model/SuiBroadcastActionDto" target="_blank" rel="noopener noreferrer"><code>SuiBroadcastActionDto</code></a>
+
+- `unsigned_tx_b64` (required): Unsigned transaction bytes encoded as base64.
+- `signatures` (required): Array of base64-encoded signatures for the transaction.
+
+#### Returned
+
+<a href="/staking-api/api-reference#model/SuiBroadcastActionResponseDto" target="_blank" rel="noopener noreferrer"><code>SuiBroadcastActionResponseDto</code></a>
+
+- `tx_digest`: Transaction digest of the broadcasted transaction.
+
+____
+
+### Stake balance
+
+Get staked balance for the given address:
+
+- Endpoint: <a href="/staking-api/api-reference#tag/sui/GET/api/v1/sui/native/stake-balance/&#123;address&#125;" target="_blank" rel="noopener noreferrer"><code>/api/v1/sui/native/stake-balance/&#123;address&#125;</code></a>
+- Method: `GET`
+
+#### Description
+
+Get staked balance information for the given Sui wallet address.
+
+#### Request parameters
+
+Path params:
+
+- `address`: Sui wallet address.
+
+#### Returned
+
+<a href="/staking-api/api-reference#model/SuiStakedBalanceResponseDto" target="_blank" rel="noopener noreferrer"><code>SuiStakedBalanceResponseDto</code></a>
+
+- `wallet_address`: Wallet address that was queried.
+- `total_mist`: Total staked balance in MIST.
+- `total_sui`: Total staked balance in SUI.
+- `staked_objects`: Array of `StakedSuiObjectDto`.
+- `fungible_objects`: Array of `FungibleStakedSuiDto`.

docs/staking-api/sui/native-staking/index.md

@@ -0,0 +1,55 @@
+---
+sidebar_position: 1
+---
+# Staking Flow
+
+Before interacting with the API methods, it is useful to understand how native staking works on Sui.
+
+Sui staking follows an object-based model. A wallet stakes SUI into a validator staking pool and receives stake-related on-chain objects. Unstaking is performed using the specific `StakedSui` object identifier.
+
+All staking operations are executed on-chain. The Stakely Staking API crafts the required transactions, while signing and broadcasting are handled by your application.
+
+### Stake
+
+Staking delegates a specified amount of SUI to a validator.
+
+1. **Initiate Stake**: Use the stake action to create a transaction that stakes a chosen amount to a validator.
+2. **Transaction Confirmation**: Once the transaction is confirmed on-chain, your stake position is created.
+3. **Stake Objects**: The wallet can then query staked positions and balances.
+
+### Unstake
+
+Unstaking starts the process of withdrawing stake from an existing `StakedSui` object.
+
+1. **Select Staked Object**: Identify the `staked_sui_object_id` to unstake.
+2. **Initiate Unstake**: Use the unstake action to craft an unstake transaction.
+3. **Transaction Confirmation**: Once confirmed on-chain, the unstake operation is applied.
+
+___
+
+## Staking API Diagram
+
+```mermaid
+sequenceDiagram
+autonumber
+actor User
+participant StakingAPI
+User->>+StakingAPI: Stake action
+Note left of User: Offline: Stake X SUI
+Note right of StakingAPI: Craft unsigned transaction
+StakingAPI-->>-User: Returns unsigned_tx_b64
+activate User
+Note left of User: Sign unsigned transaction with\nprivate key or custodian
+deactivate User
+
+User->>+StakingAPI: Prepare
+Note right of StakingAPI: Combine unsigned tx + signature(s)
+StakingAPI-->>-User: Returns signed payload
+activate User
+Note left of User: Optionally broadcast via your own RPC\nor Stakely broadcast endpoint
+deactivate User
+
+User->>+StakingAPI: Broadcast
+Note right of StakingAPI: Broadcast to Sui network
+StakingAPI-->>-User: Returns tx digest/status
+```