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

# Spice Deposits & Balances

> Record deposits/withdrawals and query user balances

## Endpoints

| Method | Endpoint                 | Description                    |
| ------ | ------------------------ | ------------------------------ |
| `POST` | `/spicedeposit`          | Record a deposit or withdrawal |
| `GET`  | `/spicedeposit/:address` | Get user token balances        |

***

## POST /spicedeposit

Record a deposit (add balance) or withdrawal (subtract balance) after on-chain verification.

### Request Body

```typescript theme={null}
{
  user: Address;         // User wallet address
  sender: Address;       // Transaction sender
  txHash: Hash;          // Transaction hash for verification
  chainId: number;       // Chain ID where tx occurred
  tokenAddress: Address; // Token contract address
  amount: bigint;        // Amount in wei
  isDeposit?: boolean;   // true = deposit (add), false = withdrawal (subtract). Default: true
}
```

### Response

**Success (200)**

```json theme={null}
{
  "success": true
}
```

**Error (400)**

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Missing txHash, sender, tokenAddress, chainId, or amount"
  }
}
```

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Spice deposit verification failed"
  }
}
```

### Verification

For deposits (`isDeposit: true`), the API verifies the transaction on-chain by:

1. Fetching the transaction receipt
2. Verifying deposit events match the claimed amount
3. Confirming the sender and token address

<Note>
  Withdrawal verification is currently pending while the exact withdrawal event signature is confirmed.
</Note>

### Example

```bash theme={null}
curl -X POST /spicedeposit \
  -H "Content-Type: application/json" \
  -d '{
    "user": "0x742d35Cc6634C0532925a3b844e4B7db0D6d8E5c",
    "sender": "0x742d35Cc6634C0532925a3b844e4B7db0D6d8E5c",
    "txHash": "0x1234567890abcdef...",
    "chainId": 84532,
    "tokenAddress": "0xTokenAddress...",
    "amount": "1000000000000000000",
    "isDeposit": true
  }'
```

***

## GET /spicedeposit/:address

Get all token balances for a user across all chains.

### Path Parameters

| Parameter | Type     | Required | Description         |
| --------- | -------- | -------- | ------------------- |
| `address` | `string` | Yes      | User wallet address |

### Response

**Success (200)**

```json theme={null}
{
  "success": true,
  "data": {
    "tokens": {
      "84532": {
        "0xTokenAddress1...": "1000000000000000000",
        "0xTokenAddress2...": "500000000000000000"
      },
      "421614": {
        "0xTokenAddress3...": "2500000000000000000"
      }
    }
  }
}
```

The `tokens` object is structured as:

* **Key (outer)**: Chain ID as string
* **Key (inner)**: Token contract address
* **Value**: Balance amount as string (in wei)

### Example

```bash theme={null}
curl /spicedeposit/0x742d35Cc6634C0532925a3b844e4B7db0D6d8E5c
```

### Response Fields

| Field    | Type     | Description                                     |
| -------- | -------- | ----------------------------------------------- |
| `tokens` | `object` | Nested mapping: chainId → tokenAddress → amount |