# Printr Staking

> Stake a Printr launch's tokens from its wallets, list the positions and claim their rewards.

For launches on Printr (Solana), launch wallets can lock tokens in Printr staking positions and earn rewards in the quote token and in the launched token. Each wallet signs its own transaction; results are reported per wallet, so a call can partly succeed.

Create and claim calls take at most 50 wallets or claims per request.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `POST /launch/printr/staking/create-position/{launch_id}`: Create staking positions
- `POST /launch/printr/staking/list-positions/{launch_id}`: List staking positions
- `POST /launch/printr/staking/claim-rewards/{launch_id}`: Claim staking rewards

## The Staking position object

A Printr staking position held by a launch wallet, with its rewards when requested.

- `info` (object): The position.
  - `owner` (string): Wallet that owns the position.
  - `position` (string): Position account, as a CAIP-10 identifier.
  - `lock_period` (enum): Lock period of the position. Possible values: `STAKING_LOCK_PERIOD_SEVEN_DAYS`, `STAKING_LOCK_PERIOD_FOURTEEN_DAYS`, `STAKING_LOCK_PERIOD_THIRTY_DAYS`, `STAKING_LOCK_PERIOD_SIXTY_DAYS`, `STAKING_LOCK_PERIOD_NINETY_DAYS`, `STAKING_LOCK_PERIOD_ONE_HUNDRED_EIGHTY_DAYS`.
  - `staked` (object): Amount staked.
    - `asset` (object): Asset reference.
      - `account` (string): Asset account.
    - `decimals` (integer): Token decimals.
    - `atomic` (string): Amount in atomic units.
    - `display` (string): Amount formatted for display.
  - `created_at` (string): Creation time, ISO 8601.
  - `unlocks_at` (string): Unlock time, ISO 8601.
  - `was_closed` (boolean): Whether the position has been closed.
- `claimable_quote_rewards` (object | null): Quote rewards claimable now.
  - `asset` (object): Asset reference.
    - `account` (string): Asset account.
  - `decimals` (integer): Token decimals.
  - `atomic` (string): Amount in atomic units.
  - `display` (string): Amount formatted for display.
- `claimable_telecoin_rewards` (object | null): Token rewards claimable now.
  - `asset` (object): Asset reference.
    - `account` (string): Asset account.
  - `decimals` (integer): Token decimals.
  - `atomic` (string): Amount in atomic units.
  - `display` (string): Amount formatted for display.
- `claimed_quote_rewards` (object | null): Quote rewards already claimed.
  - `asset` (object): Asset reference.
    - `account` (string): Asset account.
  - `decimals` (integer): Token decimals.
  - `atomic` (string): Amount in atomic units.
  - `display` (string): Amount formatted for display.
- `claimed_telecoin_rewards` (object | null): Token rewards already claimed.
  - `asset` (object): Asset reference.
    - `account` (string): Asset account.
  - `decimals` (integer): Token decimals.
  - `atomic` (string): Amount in atomic units.
  - `display` (string): Amount formatted for display.

```json
{
  "info": {
    "owner": "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
    "position": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:8kPz3VnQ7wR2tYx5mLc9HbJ4dE6sFgA1uK3rT7vNqXwe",
    "lock_period": "STAKING_LOCK_PERIOD_THIRTY_DAYS",
    "staked": {
      "decimals": 6,
      "atomic": "25000000000",
      "display": "25000"
    },
    "created_at": "2026-10-12T09:14:03Z",
    "unlocks_at": "2026-11-11T09:14:03Z",
    "was_closed": false
  },
  "claimable_quote_rewards": {
    "decimals": 9,
    "atomic": "18250000",
    "display": "0.01825"
  },
  "claimable_telecoin_rewards": {
    "decimals": 6,
    "atomic": "412000000",
    "display": "412"
  },
  "claimed_quote_rewards": null,
  "claimed_telecoin_rewards": null
}
```

### Create staking positions

`POST /launch/printr/staking/create-position/{launch_id}`

Stakes the same token amount from each selected launch wallet for the chosen lock period. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. Each call opens new positions from every selected wallet. Before retrying, call [List staking positions](/reference/printr-staking/#list-staking-positions) for the same wallets and retry only the wallets that have no new position.

> Locks tokens on-chain until the lock period ends.

#### Path parameters

- `launch_id` (string, required): Launch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (`101` Solana, `201` BSC, `202` Base, `204` Ethereum).

#### Body parameters

- `lock_period` (enum, required): How long the tokens stay locked. Possible values: `STAKING_LOCK_PERIOD_SEVEN_DAYS`, `STAKING_LOCK_PERIOD_FOURTEEN_DAYS`, `STAKING_LOCK_PERIOD_THIRTY_DAYS`, `STAKING_LOCK_PERIOD_SIXTY_DAYS`, `STAKING_LOCK_PERIOD_NINETY_DAYS`, `STAKING_LOCK_PERIOD_ONE_HUNDRED_EIGHTY_DAYS`.
- `amount` (integer, required): Tokens to stake per wallet, atomic units. Must be greater than 0.
- `wallets` (array<string>, optional): Launch wallets to stake from. Omit for all launch wallets.

#### Returns 200 OK

- `success` (boolean): `true` when at least one position was created.
- `created` (integer): Number of wallets whose position was created.
- `total` (integer): Number of wallets attempted.
- `results` (array<object>): One entry per wallet.
  - `pubkey` (string): Wallet.
  - `success` (boolean): Whether this wallet staked.
  - `signature` (string): Transaction signature.
  - `error` (string): Why this wallet failed.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a chain-encoded launch ID. | Pass the 15-digit chain-encoded launch ID exactly as the API returned it. |
| 404 | `not_found` | `launch not found` | No launch with this ID belongs to the license in your token. | Check the launch ID and that your token is upgraded onto the license that owns the launch. |
| 400 | `bad_request` | `Amount must be > 0` | `amount` is 0. | Send an `amount` greater than 0, in atomic units. |
| 400 | `bad_request` | `Maximum 50 wallets per request` | More than 50 wallets are selected, including when `wallets` is omitted and the launch has more than 50 wallets. | Pass `wallets` with at most 50 addresses per request. |
| 404 | `not_found` | `No matching wallets found` | None of `wallets` belongs to the launch. Addresses outside the launch are dropped silently as long as one matches. | Pass addresses of the launch's own wallets, or omit `wallets` to use all of them. |
| 400 | `unsupported_chain` | `this endpoint is not supported for this chain` | The launch is not on Solana. The body adds `chain`. | Call it only for Solana launches (IDs starting with `101`). |
| 400 |  | `Json deserialize error: <cause>` | The body is missing, is not valid JSON, lacks `lock_period` or `amount`, has an unknown `lock_period`, or is sent without `Content-Type: application/json`. The HTTP framework answers before the handler runs (before `launch_id` is checked) with a plain-text body, not the JSON error object. | Send a JSON body with `Content-Type: application/json` that matches the documented fields. |
| 500 | `internal_error` | `Token not launched` | The launch is still a draft: the token does not exist on chain yet. | Launch the token first with [Launch a token](/reference/launch-execution/#launch). |
| 500 | `internal_error` | `Printr api error` | Printr's token API failed or does not know the launch's mint, for example because the launch is not a Printr launch. | Check that the launch is a Printr launch, then retry in a few seconds. |
| 500 | `internal_error` | `Failed to build any staking transactions` | Printr's staking API refused or failed for every selected wallet, so nothing was sent. The per-wallet reasons are not returned. | Retry later; nothing was sent, so a retry cannot stake twice. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/printr/staking/create-position/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "lock_period": "STAKING_LOCK_PERIOD_THIRTY_DAYS",
  "amount": 25000000000,
  "wallets": [
    "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
    "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh"
  ]
}'
```

#### Example response

```json
{
  "success": true,
  "created": 2,
  "total": 2,
  "results": [
    {
      "pubkey": "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
      "success": true,
      "signature": "5VfYmGc8sT3kQ2xR9nLwP4hJ7dB6aZ1uE8yNvK3tXqMr2HcW9pLs5FjD7gA4bT6nY1kR8mQzV3xC2wE5uJ9hP7a"
    },
    {
      "pubkey": "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh",
      "success": true,
      "signature": "3kTq9WmZ2vXc7RbN5pLh8YdG4sJ6fA1uE3rK7tVnQwMx9HcP2yLs5FjD8gB4aT6nZ1kR7mQzV3xC2wE5uJ4hR8b"
    }
  ]
}
```

### List staking positions

`POST /launch/printr/staking/list-positions/{launch_id}`

Returns the staking positions held by the launch's wallets. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A read: `POST` only carries the filter.

A `POST` so the wallet filter can travel in the body; the client sends `{}` when there is no filter.

#### Path parameters

- `launch_id` (string, required): Launch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (`101` Solana, `201` BSC, `202` Base, `204` Ethereum).

#### Body parameters

- `wallets` (array<string>, optional): Launch wallets to list. Omit for all launch wallets.
- `with_rewards` (boolean, optional): Include claimable and claimed rewards.

#### Returns 200 OK

Returns a list of Staking position objects under `positions`.

- `positions` (array<object>): Staking positions.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a chain-encoded launch ID. | Pass the 15-digit chain-encoded launch ID exactly as the API returned it. |
| 404 | `not_found` | `launch not found` | No launch with this ID belongs to the license in your token. | Check the launch ID and that your token is upgraded onto the license that owns the launch. |
| 404 | `not_found` | `Wallet <address> not found in launch` | An entry of `wallets` is not one of the launch's wallets; a malformed address also lands here. | Pass only addresses of the launch's own wallets, or omit `wallets` to list them all. |
| 400 | `unsupported_chain` | `this endpoint is not supported for this chain` | The launch is not on Solana. The body adds `chain`. | Call it only for Solana launches (IDs starting with `101`). |
| 400 |  | `Json deserialize error: <cause>` | The body is missing, is not valid JSON, or is sent without `Content-Type: application/json`. The HTTP framework answers before the handler runs (before `launch_id` is checked) with a plain-text body, not the JSON error object. | Send a JSON body with `Content-Type: application/json` that matches the documented fields. |
| 500 | `internal_error` | `Printr api error` | Printr's token API failed or does not know the launch's mint, for example because the launch is not a Printr launch. | Check that the launch is a Printr launch, then retry in a few seconds. |
| 500 | `internal_error` | `Printr staking api error` | Printr's staking API failed or returned an answer the backend could not read. | Retry in a few seconds. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/printr/staking/list-positions/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "with_rewards": true
}'
```

#### Example response

```json
{
  "positions": [
    {
      "info": {
        "owner": "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
        "position": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:8kPz3VnQ7wR2tYx5mLc9HbJ4dE6sFgA1uK3rT7vNqXwe",
        "lock_period": "STAKING_LOCK_PERIOD_THIRTY_DAYS",
        "staked": {
          "decimals": 6,
          "atomic": "25000000000",
          "display": "25000"
        },
        "created_at": "2026-10-12T09:14:03Z",
        "unlocks_at": "2026-11-11T09:14:03Z",
        "was_closed": false
      },
      "claimable_quote_rewards": {
        "decimals": 9,
        "atomic": "18250000",
        "display": "0.01825"
      },
      "claimable_telecoin_rewards": {
        "decimals": 6,
        "atomic": "412000000",
        "display": "412"
      },
      "claimed_quote_rewards": null,
      "claimed_telecoin_rewards": null
    }
  ]
}
```

### Claim staking rewards

`POST /launch/printr/staking/claim-rewards/{launch_id}`

Claims the rewards of the given positions, one transaction per wallet and position. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. Before retrying, call [List staking positions](/reference/printr-staking/#list-staking-positions) with `with_rewards: true`: claimable rewards back at zero mean the first claim landed. A repeat sends a new claim transaction per position and pays its fee again.

#### Path parameters

- `launch_id` (string, required): Launch ID: the 15-digit chain-encoded ID. Its first three digits name the chain (`101` Solana, `201` BSC, `202` Base, `204` Ethereum).

#### Body parameters

- `claims` (array<object>, required): Positions to claim, at most 50.
  - `pubkey` (string, required): Launch wallet that owns the position and pays the fee.
  - `position` (string, required): Position account, as a CAIP-10 identifier.

#### Returns 200 OK

- `success` (boolean): `true` when at least one claim landed.
- `claimed` (integer): Number of claims that landed.
- `total` (integer): Number of claims attempted.
- `results` (array<object>): One entry per claim.
  - `pubkey` (string): Wallet.
  - `position` (string): Position claimed.
  - `success` (boolean): Whether the claim landed.
  - `signature` (string): Transaction signature.
  - `error` (string): Why the claim failed.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `invalid launch id format` | `launch_id` is not a chain-encoded launch ID. | Pass the 15-digit chain-encoded launch ID exactly as the API returned it. |
| 404 | `not_found` | `launch not found` | No launch with this ID belongs to the license in your token. | Check the launch ID and that your token is upgraded onto the license that owns the launch. |
| 400 | `bad_request` | `No claims provided` | `claims` is empty. | Send at least one claim. |
| 400 | `bad_request` | `Maximum 50 claims per request` | `claims` has more than 50 entries. | Split the claims into batches of at most 50. |
| 400 | `unsupported_chain` | `this endpoint is not supported for this chain` | The launch is not on Solana. The body adds `chain`. | Call it only for Solana launches (IDs starting with `101`). |
| 400 |  | `Json deserialize error: <cause>` | The body is missing, is not valid JSON, or `claims` is missing or malformed, or is sent without `Content-Type: application/json`. The HTTP framework answers before the handler runs (before `launch_id` is checked) with a plain-text body, not the JSON error object. | Send a JSON body with `Content-Type: application/json` that matches the documented fields. |
| 500 | `internal_error` | `Token not launched` | The launch is still a draft: the token does not exist on chain yet. | Launch the token first with [Launch a token](/reference/launch-execution/#launch). |
| 500 | `internal_error` | `Printr staking api error` | Printr's staking API failed while the backend looked up the positions' creation transactions. | Retry in a few seconds. |
| 500 | `internal_error` | `Failed to build any claim transactions` | No claim could be built: every `pubkey` is outside the launch, every `position` is unknown for its wallet, or Printr refused each one. Nothing was sent and the per-claim reasons are not returned. | Take the `pubkey` and `position` pairs from [List staking positions](/reference/printr-staking/#list-staking-positions) and retry. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/printr/staking/claim-rewards/101000000004217" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "claims": [
    {
      "pubkey": "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
      "position": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:8kPz3VnQ7wR2tYx5mLc9HbJ4dE6sFgA1uK3rT7vNqXwe"
    },
    {
      "pubkey": "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh",
      "position": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:4tHw9CnR2xV6mQb8LpZ3yKd7GsE5fJ1aU9rT2vNkXqMc"
    }
  ]
}'
```

#### Example response

```json
{
  "success": true,
  "claimed": 2,
  "total": 2,
  "results": [
    {
      "pubkey": "3pGh8WcR5vTn2YkLz9QmXbE7aDs4FjU6wHrN1tKyPqVe",
      "position": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:8kPz3VnQ7wR2tYx5mLc9HbJ4dE6sFgA1uK3rT7vNqXwe",
      "success": true,
      "signature": "5VfYmGc8sT3kQ2xR9nLwP4hJ7dB6aZ1uE8yNvK3tXqMr2HcW9pLs5FjD7gA4bT6nY1kR8mQzV3xC2wE5uJ9hP7a"
    },
    {
      "pubkey": "6rVb2NqT8xK4mWc9HsZpG7eYjD3uLfA5tRnE1kQwXzMh",
      "position": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp:4tHw9CnR2xV6mQb8LpZ3yKd7GsE5fJ1aU9rT2vNkXqMc",
      "success": true,
      "signature": "3kTq9WmZ2vXc7RbN5pLh8YdG4sJ6fA1uE3rK7tVnQwMx9HcP2yLs5FjD8gB4aT6nZ1kR7mQzV3xC2wE5uJ4hR8b"
    }
  ]
}
```
