# Stable Points (SP)

Build on Spree Protocol with the `@spree-finance/spree-evm-sdk`. The SDK builds unsigned transactions for offline signing and executes read-only calls against Spree smart contracts.

### Install

```bash
npm install @spree-finance/spree-evm-sdk
```

### Quick Start

```typescript
import { Factory, Points } from '@spree-finance/spree-evm-sdk';

// Configure the Factory wrapper
const factory = new Factory({
  rpcUrl: 'https://sepolia.base.org',
  chainId: 84532n,
  contractAddress: '0xFactoryAddress',
  from: '0xYourWallet',
  defaultGasPriceWei: 1_000_000_000n,
  defaultGasLimit: 500_000n,
});

// Read SP balance (no transaction, uses eth_call)
const points = new Points({ ...pointsConfig });
const balance = await points.readBalanceOf('0xUserAddress');

// Build an unsigned mint transaction
const unsignedTx = await factory.mint(
  '0xUSDCAddress',  // stablecoin asset
  1_000_000n,       // amount (6 decimals for USDC)
  '0xReceiver',     // SP recipient
  false,            // expectBasketMode
);

// Sign with your wallet, then broadcast
```

### Contract Wrappers

The SDK ships one wrapper per contract. Each wrapper accepts `BaseContractConfig` and exposes both write methods (return unsigned tx hex) and read methods (return decoded values).

| Wrapper               | Contract            | Purpose                              |
| --------------------- | ------------------- | ------------------------------------ |
| `Factory`             | Factory             | Mint SP, redeem SP, vault management |
| `Points`              | Points              | ERC-20 SP token, transfer whitelist  |
| `SpreeVault4626`      | SpreeVault4626      | ERC-4626 rewards vault               |
| `BonusRewardsVault`   | BonusRewardsVault   | Epoch-based bonus rewards            |
| `PythPriceOracle`     | PythPriceOracle     | Price feeds                          |
| `PendingSPVault`      | PendingSPVault      | Campaign-based pSP distribution      |
| `SpreeStatusRegistry` | SpreeStatusRegistry | Tier/status management               |
| `BoostEngine`         | BoostEngine         | Boost multiplier calculations        |

### Additional Modules

| Module             | Purpose                                 |
| ------------------ | --------------------------------------- |
| `ClientOnboarding` | Deploy brand infrastructure             |
| `ContractRegistry` | Query deployed factories and contracts  |
| `ERC20`            | Generic ERC-20 approve/transfer/balance |

### Guides

* [Authentication](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/authentication/README.md) - API keys, auth headers, base URLs
* [Core Token Operations](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/core-token-operations/README.md) - Mint, transfer, balance, vault creation
* [Campaign & pSP Operations](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/campaign-operations/README.md) - Create campaigns, distribute pSP
* [Whitelist Management](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/whitelist-management/README.md) - Transfer and settlement whitelists
* [Redemption Operations](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/redemption-operations/README.md) - Redeem SP back to stablecoins
* [API Reference](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/api-reference/README.md) - HTTP API endpoints
* [SDK Reference](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/sdk-reference/README.md) - Full SDK method signatures
* [Security & Role Management](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/security-role-management/README.md) - RBAC, freeze, upgradeability
* [Error Handling](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/error-handling/README.md) - Error classes, fee schedule
* [Join Ecosystem](https://github.com/Spree-Finance/spree-docs/blob/main/developer-guides/stable-points-sp/join-ecosystem/README.md) - Get started as a brand or developer


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://spree-finance.gitbook.io/spreefinance/developer-guides/stable-points-sp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.