Bills

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

Get All Bills

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

{
	"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

GET /bills/{id}

Retrieves details of a specific bill.

Response

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

Get Bill Activities

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

{
	"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

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

{
	"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

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

{
	"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

GET /bills/account/{address}/activities

Retrieves bill activities for a specific account.

Query Parameters

Same as Get Bill Activities

Get Account Bill Stats

GET /bills/account/{address}/stats

Retrieves bill statistics for a specific account.

Response

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