Documentation

Mortar serves Mosaic bounty data over HTTP and websocket. Contract state remains settlement authority.

HTTP Routes

Method	Route	Return
`GET`	`/health`	Service status and indexer flags.
`GET`	`/bounties`	Bounty records or a paged bounty response.
`GET`	`/bounties/{bounty_id}`	One bounty record.
`GET`	`/bounties/{bounty_id}/overview`	One bounty, its submissions, and their disputes.
`GET`	`/submissions`	Submission records or a paged submission response.
`GET`	`/submissions?bounty_id={id}`	Submission records for one bounty.
`GET`	`/submissions/{submission_id}`	One submission record.
`GET`	`/submissions/{submission_id}/overview`	One submission, its bounty, and its disputes.
`GET`	`/disputes`	Dispute records or a paged dispute response.
`GET`	`/disputes?bounty_id={id}`	Paged dispute records for one bounty.
`GET`	`/disputes?submission_id={id}`	Dispute records for one submission.
`GET`	`/disputes/{dispute_id}`	One dispute record.
`GET`	`/disputes/{dispute_id}/overview`	One dispute, its submission, its bounty, and sibling disputes.

Single-record and overview routes return 404 when the target record is unavailable.

List Query Params

List routes accept:

Param	Meaning
`limit`	Page size from `1` to `100`. Defaults to `50` for paged responses.
`cursor`	Offset cursor returned by a prior page. Invalid cursors read from `0`.
`q`	Text search across IDs, status, actors, metadata, transaction hash, and route-specific text fields.
`sort`	Sort key. Unknown values use `id`.
`dir`	`asc` or `desc`. Unknown values use `desc`.
`chain_id`	Deployment chain filter. The active GIWA Sepolia chain ID is `91342`.
`contract_address`	Deployment contract filter. Use with `chain_id` for collision-safe reads.

GET /bounties, GET /submissions, and GET /disputes return unpaged arrays when no paging or search params are supplied. Supplying limit, cursor, or q returns a page object. GET /disputes?bounty_id=... also returns a page object.

Page object:

{
  "items": [],
  "total": 0,
  "limit": 50,
  "cursor": null,
  "next_cursor": null
}

Bounty page rows include submission_count. Submission page rows and submission overview records include dispute_count.

Every bounty, submission, and dispute record includes chain_id and contract_address. IDs are only unique within a deployment. Always send both fields on single-record and overview routes. Parent filters using bounty_id or submission_id also require both deployment fields.

Sort keys:

Bounties: id, created_at, deadline, reward, bounty_amount, bond, bond_amount, status, poster, prompt, submissions, submission_count.
Submissions: id, created_at, submitted, bounty, bounty_id, bond, bond_amount, status, claimant, content, review, review_deadline, disputes, dispute_count.
Disputes: id, created_at, submitted, bounty, bounty_id, submission, submission_id, bond, bond_amount, status, challenger, reason.

Bounty Fields

Field	Meaning
`id`	Bounty ID.
`chain_id`	Deployment chain ID.
`contract_address`	Mosaic deployment address.
`prompt`	Stored prompt field. Current indexer mirrors `metadata_uri` here.
`bounty_amount`	Reward amount in USDC base units.
`fee_amount`	Post fee amount in USDC base units.
`bond_amount`	Submission bond in USDC base units.
`duration`	Bounty duration in seconds.
`status`	`open`, `resolved`, or `refunded`.
`poster`	Poster address.
`deadline`	Bounty deadline timestamp.
`challenge_window`	Review window in seconds.
`metadata_uri`	Bounty metadata URI.
`metadata_hash`	Bounty metadata hash.
`tx_hash`	Source transaction hash.
`block_number`	Source block number.
`log_index`	Source log index.
`created_at`	Mortar row creation timestamp.
`submission_count`	Included on paged and overview bounty records.

Submission Fields

Field	Meaning
`id`	Submission ID.
`chain_id`	Deployment chain ID.
`contract_address`	Mosaic deployment address.
`bounty_id`	Parent bounty ID.
`tile_id`	Submitter address field.
`content`	Stored content field. Current indexer mirrors `metadata_uri` here.
`bond_amount`	Submission bond in USDC base units.
`review_deadline`	Submission review deadline timestamp.
`status`	`submitted`, `disputed`, `accepted`, `rejected`, or `refunded`.
`claimant`	Submitter address.
`metadata_uri`	Submission metadata URI.
`metadata_hash`	Submission metadata hash.
`tx_hash`	Source transaction hash.
`block_number`	Source block number.
`log_index`	Source log index.
`created_at`	Mortar row creation timestamp.
`dispute_count`	Included on paged and overview submission records.

Dispute Fields

Field	Meaning
`id`	Dispute ID.
`chain_id`	Deployment chain ID.
`contract_address`	Mosaic deployment address.
`bounty_id`	Parent bounty ID.
`submission_id`	Disputed submission ID.
`challenger_id`	Grout address.
`reason`	Stored reason field. Current indexer mirrors `metadata_uri` here.
`bond_amount`	Dispute bond in USDC base units.
`status`	`pending_human_review`, `upheld`, `rejected`, or `cancelled`.
`metadata_uri`	Dispute metadata URI.
`metadata_hash`	Dispute metadata hash.
`tx_hash`	Source transaction hash.
`block_number`	Source block number.
`log_index`	Source log index.
`created_at`	Mortar row creation timestamp.

HTTP Caching and Limits

Read responses include Cache-Control and weak ETag headers. Supplying a matching If-None-Match returns 304.

HTTP rate limits apply to every route except /health. Rate-limited responses return 429 with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Websocket

WS /ws/events

Connection sequence:

Current bounty records for the configured active deployment.
Current submission records for the configured active deployment.
Current dispute records for the configured active deployment.
Live updates.

Websocket connection and message limits close the socket with code 1008 when exceeded.

Websocket Payloads

Type	Payload
`bounty.created`	Bounty record.
`submission.created`	Submission record.
`dispute.created`	Dispute record.
`dispute.resolved`	Dispute record.
`dispute.cancelled`	Dispute record.
`bounty.finalized`	Bounty record.
`bounty.refunded`	Bounty record.
`submission.refunded`	Submission record.

Mortar API