> For the complete documentation index, see [llms.txt](https://spree-finance.gitbook.io/spreefinance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spree-finance.gitbook.io/spreefinance/developer-guides/stable-points-sp/api-reference.md).

# API Reference

### Base URLs

| Environment | URL                                    |
| ----------- | -------------------------------------- |
| Staging     | `https://api.stg.spree.finance/api/v1` |

### Authentication

Include your API key as a Bearer token:

```
Authorization: Bearer YOUR_API_KEY
```

### Request Format

All build endpoints accept POST with this body:

```json
{
  "input": {
    "asset": "0x...",
    "amount": "1000000"
  },
  "key": "0xSignerAddress"
}
```

Build endpoints return a base64-encoded unsigned transaction. Read endpoints return chain data as JSON.

### Response Format

Success:

```json
{
  "success": true,
  "data": {
    "tx": "base64EncodedUnsignedTransaction"
  }
}
```

Error:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Description of what went wrong"
  }
}
```

### Build Routes

Build routes construct unsigned transactions. No auth required for testnet.

| Method | Path                     | Description                       |
| ------ | ------------------------ | --------------------------------- |
| POST   | `/build/mint`            | Build mint SP transaction         |
| POST   | `/build/redeem`          | Build redeem request transaction  |
| POST   | `/build/finalize-redeem` | Build finalize redeem transaction |
| POST   | `/build/transfer`        | Build SP transfer transaction     |

### Read Routes

Read routes query on-chain state. No auth required.

| Method | Path                        | Description                 |
| ------ | --------------------------- | --------------------------- |
| GET    | `/evm/balance/:address`     | Get SP balance              |
| GET    | `/evm/factory/state`        | Get factory state           |
| GET    | `/evm/factory/assets`       | List registered assets      |
| GET    | `/evm/factory/vault/:asset` | Get vault address for asset |

### Role Management Routes

| Method | Path                                    | Description                   |
| ------ | --------------------------------------- | ----------------------------- |
| PUT    | `/roles/grant`                          | Grant a role to an address    |
| DELETE | `/roles/revoke`                         | Revoke a role from an address |
| GET    | `/roles/check/:contract/:role/:address` | Check if address has role     |

#### Grant Role

```bash
curl -X PUT https://api.stg.spree.finance/api/v1/roles/grant \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "contract": "factory",
      "role": "EXECUTOR_ROLE",
      "account": "0xTargetAddress"
    },
    "key": "0xAdminAddress"
  }'
```

#### Revoke Role

```bash
curl -X DELETE https://api.stg.spree.finance/api/v1/roles/revoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "contract": "factory",
      "role": "EXECUTOR_ROLE",
      "account": "0xTargetAddress"
    },
    "key": "0xAdminAddress"
  }'
```

#### Check Role

```bash
curl https://api.stg.spree.finance/api/v1/roles/check/factory/EXECUTOR_ROLE/0xAddress
```

### Freeze Routes

| Method | Path              | Description        |
| ------ | ----------------- | ------------------ |
| POST   | `/freeze/pause`   | Pause a contract   |
| POST   | `/freeze/unpause` | Unpause a contract |

```bash
curl -X POST https://api.stg.spree.finance/api/v1/freeze/pause \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "contract": "factory" },
    "key": "0xPauserAddress"
  }'
```

### Contract Query Routes

| Method | Path                        | Description                 |
| ------ | --------------------------- | --------------------------- |
| GET    | `/contracts/factories`      | List all deployed factories |
| GET    | `/contracts/factories/:id`  | Get factory by ID           |
| GET    | `/contracts/chain/:chainId` | Get contracts by chain      |