Documentation Index
Fetch the complete documentation index at: https://docs.nexfi.robert.dpdns.org/llms.txt
Use this file to discover all available pages before exploring further.
Staking Catalog and Transactions
This page mirrors the detailed design style for Staking user-side APIs, including endpoint purpose, request parameters, response fields, examples, and product notes.
GET /api/v1/staking/products
Purpose
Returns staking product catalog items for list pages and filtered discovery.
Query Parameters
| Parameter | Type | Required | Description | Example |
|---|
chainId | Integer | No | Chain ID filter. | 8453 |
productType | String | No | Product type filter such as aggregated or vault. | vault |
riskLevel | String | No | Risk level filter. | medium |
assetSymbol | String | No | Subscription asset symbol. | USDC |
status | String | No | Product status filter. | active |
Response Fields
| Field | Type | Description | Example |
|---|
data.items | Array | Product list. | [] |
data.items[].id | String | Product ID. | base_usdc_nexfi_vault |
data.items[].name | String | Product name. | NexFi USDC Yield Vault |
data.items[].productType | String | Product type. | vault |
data.items[].chainId | Integer | Chain ID. | 8453 |
data.items[].assetSymbol | String | Subscription asset symbol. | USDC |
data.items[].apy | String | Current APY. | 7.25 |
data.items[].tvlUsd | String | TVL in USD. | 1200000 |
data.items[].riskLevel | String | Risk level. | medium |
data.items[].status | String | Product status. | active |
data.items[].tags | String[] | Product display tags. | ["Stable","Featured"] |
Example Response
{
"code": 0,
"msg": "ok",
"data": {
"items": [
{
"id": "base_usdc_nexfi_vault",
"name": "NexFi USDC Yield Vault",
"productType": "vault",
"chainId": 8453,
"assetSymbol": "USDC",
"apy": "7.25",
"tvlUsd": "1200000",
"riskLevel": "medium",
"status": "active",
"tags": ["Stable", "Featured"]
}
]
}
}
GET /api/v1/staking/products/{id}
Purpose
Returns one staking product detail for detail pages and transaction confirmation flows.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|
id | String | Yes | Product ID. | base_usdc_nexfi_vault |
Response Fields
| Field | Type | Description | Example |
|---|
data.id | String | Product ID. | base_usdc_nexfi_vault |
data.name | String | Product name. | NexFi USDC Yield Vault |
data.productType | String | Product type. | vault |
data.chainId | Integer | Chain ID. | 8453 |
data.apy | String | APY. | 7.25 |
data.tvlUsd | String | TVL in USD. | 1200000 |
data.riskLevel | String | Risk level. | medium |
data.rewardSource | String | Yield source summary. | Vault strategy yield |
data.lockRule | String | Lock rule summary. | No hard lock |
data.exitRule | String | Exit rule summary. | ERC-4626 redeem |
data.status | String | Product status. | active |
Example Response
{
"code": 0,
"msg": "ok",
"data": {
"id": "base_usdc_nexfi_vault",
"name": "NexFi USDC Yield Vault",
"productType": "vault",
"chainId": 8453,
"apy": "7.25",
"tvlUsd": "1200000",
"riskLevel": "medium",
"rewardSource": "Vault strategy yield",
"lockRule": "No hard lock",
"exitRule": "ERC-4626 redeem",
"status": "active"
}
}
GET /api/v1/staking/positions
Purpose
Returns user staking positions for portfolio views, earnings summaries, and product detail overlays.
Query Parameters
| Parameter | Type | Required | Description | Example |
|---|
walletAddress | String | Yes | Wallet address. | 0xabc... |
chainId | Integer | No | Chain ID filter. | 8453 |
status | String | No | Position status filter. | active |
Response Fields
| Field | Type | Description | Example |
|---|
data.items | Array | Position list. | [] |
data.items[].productId | String | Product ID. | base_usdc_nexfi_vault |
data.items[].walletAddress | String | Wallet address. | 0xabc... |
data.items[].shares | String | Share amount. | 998.12 |
data.items[].assetAmount | String | Underlying asset amount. | 1000 |
data.items[].status | String | Position status. | active |
data.items[].updatedAt | String | Last update time. | 2026-05-11T10:00:00.000Z |
Example Response
{
"code": 0,
"msg": "ok",
"data": {
"items": [
{
"productId": "base_usdc_nexfi_vault",
"walletAddress": "0xabc...",
"shares": "998.12",
"assetAmount": "1000",
"status": "active",
"updatedAt": "2026-05-11T10:00:00.000Z"
}
]
}
}
POST /api/v1/staking/transactions/build
Purpose
Builds subscribe or redeem transaction payloads for local wallet signing.
Request Body
| Parameter | Type | Required | Description | Example |
|---|
productId | String | Yes | Product ID. | base_usdc_nexfi_vault |
orderType | String | Yes | subscribe or redeem. | subscribe |
walletAddress | String | Yes | Wallet address. | 0xabc... |
amount | String | Yes | Order amount. | 1000 |
Example Request
{
"productId": "base_usdc_nexfi_vault",
"orderType": "subscribe",
"walletAddress": "0xabc...",
"amount": "1000"
}
Response Fields
| Field | Type | Description | Example |
|---|
data.buildId | String | Build result ID. | build_20260511_0001 |
data.chainId | Integer | Target chain ID. | 8453 |
data.to | String | Target contract address. | 0xvault... |
data.value | String | Native token value. | 0 |
data.data | String | Transaction calldata. | 0xb6b55f25 |
data.gasLimit | String | Suggested gas limit. | 280000 |
data.warnings | String[] | UX warnings shown before signing. | [] |
data.sharesPreview | String | Previewed shares for vault products. | 998.12 |
data.feePreview | String | Previewed fee amount. | 1.50 |
data.vaultAddress | String | Vault address for vault products. | 0xvault... |
Example Response
{
"code": 0,
"msg": "ok",
"data": {
"buildId": "build_20260511_0001",
"chainId": 8453,
"to": "0xvault000000000000000000000000000000000001",
"value": "0",
"data": "0xb6b55f25",
"gasLimit": "280000",
"warnings": ["APY is estimated and not guaranteed"],
"sharesPreview": "998.12",
"feePreview": "1.50",
"vaultAddress": "0xvault000000000000000000000000000000000001"
}
}
POST /api/v1/staking/orders
Purpose
Creates a platform staking order for lifecycle tracking after the client has prepared or submitted the chain transaction.
Request Body
| Parameter | Type | Required | Description | Example |
|---|
buildId | String | Yes | Transaction build ID. | build_20260511_0001 |
productId | String | Yes | Product ID. | base_usdc_nexfi_vault |
orderType | String | Yes | subscribe or redeem. | subscribe |
walletAddress | String | Yes | Wallet address. | 0xabc... |
amount | String | Yes | Order amount. | 1000 |
txHash | String | Yes | Submitted chain transaction hash. | 0x123... |
Example Request
{
"buildId": "build_20260511_0001",
"productId": "base_usdc_nexfi_vault",
"orderType": "subscribe",
"walletAddress": "0xabc...",
"amount": "1000",
"txHash": "0x123..."
}
Response Fields
| Field | Type | Description | Example |
|---|
data.orderId | String | Platform order ID. | stk_20260511_0001 |
data.status | String | Initial order status. | pending_chain |
Example Response
{
"code": 0,
"msg": "ok",
"data": {
"orderId": "stk_20260511_0001",
"status": "pending_chain"
}
}
GET /api/v1/staking/orders/{id}
Purpose
Returns detail of one staking order.
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|
id | String | Yes | Platform order ID. | stk_20260511_0001 |
Response Fields
| Field | Type | Description | Example |
|---|
data.orderId | String | Platform order ID. | stk_20260511_0001 |
data.productId | String | Product ID. | base_usdc_nexfi_vault |
data.walletAddress | String | Wallet address. | 0xabc... |
data.orderType | String | Order type. | subscribe |
data.status | String | Order status. | confirmed |
data.txHash | String | Chain transaction hash. | 0x123... |
data.updatedAt | String | Last update time. | 2026-05-11T10:00:00.000Z |
Example Response
{
"code": 0,
"msg": "ok",
"data": {
"orderId": "stk_20260511_0001",
"productId": "base_usdc_nexfi_vault",
"walletAddress": "0xabc...",
"orderType": "subscribe",
"status": "confirmed",
"txHash": "0x123...",
"updatedAt": "2026-05-11T10:00:00.000Z"
}
}
GET /api/v1/staking/vaults/{id}/preview
Purpose
Returns preview data for vault deposit or redeem actions.
Path / Query Parameters
| Parameter | Type | Required | Description | Example |
|---|
id | String | Yes | Vault product ID. | base_usdc_nexfi_vault |
assets | String | No | Asset amount input. Mutually exclusive with shares. | 1000 |
shares | String | No | Share amount input. Mutually exclusive with assets. | 998.12 |
Response Fields
| Field | Type | Description | Example |
|---|
data.assets | String | Asset input amount. | 1000 |
data.sharesPreview | String | Previewed shares minted. | 998.12 |
data.withdrawAssetsPreview | String | Previewed assets returned on redeem. | 999.50 |
data.feePreview | String | Previewed fee amount. | 1.50 |
data.pricePerShare | String | Current price per share. | 1.0019 |
Example Response
{
"code": 0,
"msg": "ok",
"data": {
"assets": "1000",
"sharesPreview": "998.12",
"withdrawAssetsPreview": "999.50",
"feePreview": "1.50",
"pricePerShare": "1.0019"
}
}
Notes
assets and shares should not be sent together.- Preview values are advisory and should not be treated as guaranteed settlement results.
- APY, TVL, and earnings-related values may be eventually consistent and should expose update timestamps in UI where relevant.