# Bills

The Bills API provides endpoints to query bills, their activities, participants, and payments.

## Get All Bills

```http
GET /bills
```

Retrieves a paginated list of bills with filtering options.

### Query Parameters

| Parameter   | Type   | Description                                   |
| ----------- | ------ | --------------------------------------------- |
| `page`      | number | Page number (min: 1, default: 1)              |
| `limit`     | number | Items per page (max: 100, default: 10)        |
| `creator`   | string | Filter by creator address                     |
| `manager`   | string | Filter by manager address                     |
| `status`    | string | Filter by status                              |
| `coinType`  | string | Filter by coin type                           |
| `search`    | string | Search bills (min: 3 chars)                   |
| `sortBy`    | string | Sort field (CREATED\_AT, TOTAL\_AMOUNT, etc.) |
| `sortOrder` | string | Sort order (ASC/DESC)                         |

### Bill Status Types

* `INPROGRESS`: Bill is active and accepting payments
* `PAID`: Bill has received full payment
* `COMPLETED`: Bill has been claimed
* `CANCELED`: Bill has been cancelled
* `REJECTED`: Bill has been rejected
* `REFUNDED`: Bill has been refunded
* `PENDING`: Bill is pending activation

### Response

```json
{
	"data": [
		{
			"id": "123e4567-e89b-12d3-a456-426614174000",
			"creator": "0x1234567890abcdef",
			"manager": "0x1234567890abcdef",
			"coinType": "0x2::sui::SUI",
			"amount": "1000000",
			"billType": "ONE_TIME",
			"status": "INPROGRESS",
			"interval": 2592000,
			"expiresAt": 1703116800000,
			"nextPaymentDue": 1703116800000,
			"totalPaymentsMade": 5,
			"totalAmountPaid": "500000",
			"totalAmountClaimed": "300000",
			"totalFeeAmount": "1000",
			"totalAmountRefunded": "50000",
			"description": "Monthly rent payment",
			"createdAt": "2024-01-01T00:00:00Z",
			"updatedAt": "2024-01-01T00:00:00Z"
		}
	],
	"meta": {
		"page": 1,
		"limit": 10,
		"total": 100
	}
}
```

## Get Bill by ID

```http
GET /bills/{id}
```

Retrieves details of a specific bill.

### Response

```json
{
	"data": {
		// Bill object (same as above)
	}
}
```

## Get Bill Activities

```http
GET /bills/{id}/activities
```

Retrieves activities for a specific bill.

### Query Parameters

| Parameter      | Type   | Description                            |
| -------------- | ------ | -------------------------------------- |
| `page`         | number | Page number (min: 1, default: 1)       |
| `limit`        | number | Items per page (max: 100, default: 10) |
| `activityType` | string | Filter by activity type                |
| `actor`        | string | Filter by actor address                |
| `startDate`    | string | Filter after date                      |
| `endDate`      | string | Filter before date                     |

### Activity Types

* `CREATED`
* `PAYMENT_MADE`
* `PAID`
* `COMPLETED`
* `CANCELED`
* `REJECTED`
* `PAYMENT_REFUNDED`
* `PAYMENT_CLAIMED`

### Response

```json
{
	"data": [
		{
			"id": "123e4567-e89b-12d3-a456-426614174000",
			"billId": "123e4567-e89b-12d3-a456-426614174001",
			"activityType": "CREATED",
			"actor": "0x1234567890abcdef",
			"data": {
				"amount": "1000000",
				"reason": "Bill created"
			},
			"checkpointSequenceNumber": 12345,
			"transactionDigest": "HkPwB75KXX4bQH5Vr6oYpwgwwRSSFJJf6eNFEwAd67N8",
			"createdAt": "2024-01-01T00:00:00Z"
		}
	],
	"meta": {
		"page": 1,
		"limit": 10,
		"total": 100
	}
}
```

## Get Bill Participants

```http
GET /bills/{id}/participants
```

Retrieves participants of a specific bill.

### Query Parameters

| Parameter       | Type   | Description                                    |
| --------------- | ------ | ---------------------------------------------- |
| `page`          | number | Page number (min: 1, default: 1)               |
| `limit`         | number | Items per page (max: 100, default: 10)         |
| `paymentStatus` | string | Filter by payment status (paid/partial/unpaid) |
| `search`        | string | Search by address (min: 3 chars)               |
| `sortBy`        | string | Sort field                                     |
| `sortOrder`     | string | Sort order (ASC/DESC)                          |

### Response

```json
{
	"data": [
		{
			"id": "123e4567-e89b-12d3-a456-426614174000",
			"billId": "123e4567-e89b-12d3-a456-426614174001",
			"participant": "0x1234567890abcdef",
			"role": "payer",
			"stats": {
				"totalPaid": 500.5,
				"totalPaidAmount": 1000,
				"remainingAmount": 499.5,
				"paymentCount": 3,
				"paymentProgress": 50.05
			},
			"createdAt": "2024-01-01T00:00:00Z",
			"updatedAt": "2024-01-01T00:00:00Z"
		}
	],
	"meta": {
		"page": 1,
		"limit": 10,
		"total": 100
	}
}
```

## Get Bill Payments

```http
GET /bills/{id}/payments
```

Retrieves payments made for a specific bill.

### Query Parameters

| Parameter   | Type   | Description                            |
| ----------- | ------ | -------------------------------------- |
| `page`      | number | Page number (min: 1, default: 1)       |
| `limit`     | number | Items per page (max: 100, default: 10) |
| `payer`     | string | Filter by payer address                |
| `status`    | string | Filter by status (COMPLETED/REFUNDED)  |
| `startDate` | string | Filter after date                      |
| `endDate`   | string | Filter before date                     |
| `minAmount` | number | Minimum amount                         |
| `maxAmount` | number | Maximum amount                         |

### Response

```json
{
	"data": [
		{
			"id": "123e4567-e89b-12d3-a456-426614174000",
			"paymentIndex": 1,
			"billId": "123e4567-e89b-12d3-a456-426614174001",
			"payer": "0x1234567890abcdef",
			"amount": "1000000",
			"status": "COMPLETED",
			"createdAt": "2024-01-01T00:00:00Z",
			"updatedAt": "2024-01-01T00:00:00Z"
		}
	],
	"meta": {
		"page": 1,
		"limit": 10,
		"total": 100
	}
}
```

## Get Account Bill Activities

```http
GET /bills/account/{address}/activities
```

Retrieves bill activities for a specific account.

### Query Parameters

Same as [Get Bill Activities](#get-bill-activities)

## Get Account Bill Stats

```http
GET /bills/account/{address}/stats
```

Retrieves bill statistics for a specific account.

### Response

```json
{
	"data": {
		"unclaimedAmounts": [
			{
				"coinType": "0x2::sui::SUI",
				"amount": "1000000"
			}
		],
		"claimedAmounts": [
			{
				"coinType": "0x2::sui::SUI",
				"amount": "500000"
			}
		],
		"billsByStatus": [
			{
				"status": "INPROGRESS",
				"count": 5
			}
		]
	}
}
```
