> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hubra.app/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /stake

> Build a Solana transaction that stakes the strategy's input asset. Returns base64 unsigned (or partially signed) bytes.

```http theme={null}
POST https://hubra.app/api/v1/stake
```

Build a Solana transaction that stakes `amount` of the strategy's input asset. The returned `transaction` is **base64-encoded**:

* **Unsigned** for `sol-liquid-stake`, `sol-leveraged-stake`, and `usdc-earn`.
* **Partially signed** for `sol-native-stake` (the stake-account slot is pre-signed by the server; you only sign the wallet slot).

The agent signs locally and broadcasts via [`POST /api/v1/broadcast`](https://docs.hubra.app/developer/endpoints/broadcast).

***

## Request

```bash theme={null}
curl -X POST https://hubra.app/api/v1/stake \
  -H 'Content-Type: application/json' \
  -d '{
    "strategy": "sol-liquid-stake",
    "wallet":   "<your-wallet>",
    "amount":   "1.5"
  }'
```

| Field | Type | Required | Description |
| - | - | - | - |
| `strategy` | `"sol-native-stake" \| "sol-liquid-stake" \| "sol-leveraged-stake" \| "usdc-earn"` | yes | Which strategy to stake into. |
| `wallet` | `string` | yes | Solana wallet pubkey (base58) that will sign the transaction. |
| `amount` | `string` | yes | Amount to stake, decimal string. The input asset is the strategy's `asset` — **SOL** for the three `sol-*` keys (including `sol-leveraged-stake`), USDC for `usdc-earn`. |
| `referral_code` | `string` | no | A referral code. Credits the staking wallet to the code's owner. Can also be sent as the `X-Referral-Code` header instead of in the body. See [Referral attribution](#referral-attribution). |

***

## Referral attribution

Pass a `referral_code` on a stake call and the staking wallet is credited to the code's owner. This is Hubra's native referral model — the same relationship the web app records — so a wallet's `referred_by` is set to the code owner's wallet.

If you're a Hubra **partner** (protocol, dev, or creator), your referral code from [partner.hubra.app](https://partner.hubra.app) resolves to your payout wallet, so wallets that stake with your code show up on your [partner dashboard](https://partner.hubra.app). But any referrer's code works — a partner is just a referrer.

Send the code either as a body field or a header:

```bash theme={null}
# As a body field
curl -X POST https://hubra.app/api/v1/stake \
  -H 'Content-Type: application/json' \
  -d '{
    "strategy":      "sol-liquid-stake",
    "wallet":        "<end-user-wallet>",
    "amount":        "1.5",
    "referral_code": "HUBAB23"
  }'

# …or as a header (keeps the code out of the JSON body)
curl -X POST https://hubra.app/api/v1/stake \
  -H 'Content-Type: application/json' \
  -H 'X-Referral-Code: HUBAB23' \
  -d '{"strategy":"sol-liquid-stake","wallet":"<end-user-wallet>","amount":"1.5"}'
```

> [!NOTE]
>
> Attribution is **first-write-wins** per wallet: the first referrer to bring a wallet in keeps the credit, and a wallet is never credited to itself. Passing a code is optional — omit it and the stake behaves exactly as before. A code is matched case-insensitively (`^[A-Z0-9]{4,12}$`); if you pass one that is malformed or does not resolve, the call returns `400 invalid_request` or `404 not_found` so you notice rather than silently losing attribution.

***

## Response — `sol-native-stake`

The server generates a fresh stake-account keypair and pre-signs that signature slot. The agent only signs as the wallet. **Save the returned `stakeAccount` pubkey** — you need it for future deactivate / withdraw / instant-unstake calls against this position.

```json theme={null}
{
  "strategy":                  "sol-native-stake",
  "transaction":               "<base64 partially-signed tx>",
  "hubra_token":               "<token to pass to /broadcast>",
  "stakeAccount":              "<new pubkey to track>",
  "voteAccount":               "7K8DVxtNJGnMtUY1CQJT5jcs8sFGSZTDiG7kowvFpECh",
  "rentExemptReserveLamports": 2282880,
  "delegatedLamports":         1500000000,
  "signers":                   ["<your-wallet>"],
  "notes":                     "Stake account keypair was generated and pre-signed server-side."
}
```

Broadcast via `route: "rpc"` (no Sanctum involvement on the create + delegate path).

***

## Response — `sol-liquid-stake` (Sanctum-routed)

```json theme={null}
{
  "strategy":      "sol-liquid-stake",
  "transaction":   "<base64 unsigned tx>",
  "hubra_token":   "<token to pass to /broadcast>",
  "route":         "sanctum",
  "sanctumKind":   "token",
  "sanctum_order": { "...": "..." },
  "signers":       ["<your-wallet>"]
}
```

When `route: "sanctum"`, the response also carries `sanctumKind` and `sanctum_order`. **All three (`hubra_token`, `sanctumKind`, `sanctum_order`) must be passed back to `/broadcast`** if you want Sanctum's MEV-protected broadcaster. Sanctum's execute endpoint validates the signed transaction against the original order and rejects mismatches.

Plain RPC (`route: "rpc"` at broadcast) works without the Sanctum-specific fields, but loses Sanctum's broadcaster guarantees.

***

## Response — `usdc-earn` (Voltr-routed)

```json theme={null}
{
  "strategy":    "usdc-earn",
  "transaction": "<base64 unsigned tx>",
  "hubra_token": "<token to pass to /broadcast>",
  "route":       "voltr",
  "signers":     ["<your-wallet>"]
}
```

Voltr-routed responses do not include `sanctum_order`. Broadcast via `route: "rpc"` — that is the only supported broadcast path for Voltr transactions.

***

## Response — `sol-leveraged-stake` (raSOL Max)

`amount` is **SOL**. The server builds a **single transaction** that does the whole conversion: create the raSOL ATA (idempotent) → SPL stake-pool `DepositSol` (SOL → raSOL) → Voltr `depositVault` (raSOL → raSOL Max LP). One signature, atomic.

```json theme={null}
{
  "strategy":             "sol-leveraged-stake",
  "transaction":          "<base64 unsigned tx>",
  "hubra_token":          "<token to pass to /broadcast>",
  "route":                "rpc",
  "depositedSolLamports": "20000000",
  "stagedRasolLamports":  "16700000",
  "receiptMint":          "CJEYakpjmKBvvUzAn3HJSs9vtijnv472T8YJEV3WzToF",
  "receiptSymbol":        "raSOL Max",
  "signers":              ["<your-wallet>"]
}
```

Broadcast via `route: "rpc"` — no Sanctum or Voltr execute leg. After it confirms, read your raSOL Max LP balance on-chain; you pass that figure to [`POST /api/v1/unstake`](https://docs.hubra.app/developer/endpoints/unstake) to burn the position later.

> [!NOTE]
>
> The API deposits **SOL only** — the SOL → raSOL leg is built in for you. There is no "deposit raSOL directly" variant on the agent surface. The Voltr leg is sized from the exact raSOL the stake-pool mint produces (the same floor-rounded `lamports × supply / total_lamports` the pool applies on-chain), so the staged raSOL always matches what the deposit instruction expects.

***

## The `hubra_token`

Every `/stake` (and `/unstake`) response includes a `hubra_token` HMAC'd over the message bytes of the unsigned transaction. `POST /api/v1/broadcast` requires this token and rejects any transaction that was not built by Hubra. **Save it alongside the transaction and pass it back when broadcasting.**

Tokens expire \~2 minutes after issue (matching Solana's blockhash window). If your token expires, rebuild via `/stake`.

For the full mechanics, see [Hubra token](https://docs.hubra.app/developer/hubra-token.md).

***

## Examples

```bash theme={null}
# Native delegation to Hubra's validator
curl -X POST https://hubra.app/api/v1/stake \
  -H 'Content-Type: application/json' \
  -d '{"strategy":"sol-native-stake","wallet":"<your-wallet>","amount":"1.0"}'

# Liquid: SOL → raSOL via Sanctum
curl -X POST https://hubra.app/api/v1/stake \
  -H 'Content-Type: application/json' \
  -d '{"strategy":"sol-liquid-stake","wallet":"<your-wallet>","amount":"1.0"}'

# Leveraged: SOL → raSOL → raSOL Max in one tx
curl -X POST https://hubra.app/api/v1/stake \
  -H 'Content-Type: application/json' \
  -d '{"strategy":"sol-leveraged-stake","wallet":"<your-wallet>","amount":"1.0"}'

# USDC vault deposit
curl -X POST https://hubra.app/api/v1/stake \
  -H 'Content-Type: application/json' \
  -d '{"strategy":"usdc-earn","wallet":"<your-wallet>","amount":"100"}'
```

***

## Errors

| Status | Slug | When |
| - | - | - |
| `400` | `invalid_request` | Missing or malformed fields, including a `referral_code` that isn't `^[A-Z0-9]{4,12}$`. |
| `404` | `not_found` | Unknown strategy key, or a `referral_code` (or `X-Referral-Code`) that doesn't resolve to any referrer. |
| `502` | `upstream_error` | Sanctum / Voltr could not build the transaction (wallet does not exist on-chain, no associated token account, insufficient liquidity for size). |
| `503` | `service_unavailable` | Strategy is announced but not live. |

***

## See also

> [card] [POST /unstake](https://docs.hubra.app/developer/endpoints/unstake.md)
>
> Reverse the position.

> [card] [POST /broadcast](https://docs.hubra.app/developer/endpoints/broadcast.md)
>
> Submit the signed transaction.

> [card] [Hubra token](https://docs.hubra.app/developer/hubra-token.md)
>
> The HMAC gate.

> [card] [Strategies](https://docs.hubra.app/developer/strategies.md)
>
> All strategy keys.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.