curl -X POST https://api.opencontract.io/v1/contracts/contract_xyz789/checkpoint \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"fromSequence": 1,
"toSequence": 100,
"merkleRoot": "0x...",
"lastReceiptHash": "0x...",
"teeMeasurement": "0x...",
"teeSignature": "0x...",
"checkpointedAt": "2026-08-25T21:00:00Z",
"data": { "successCount": 94, "providerErrorCount": 3 }
}'
{
"data": {
"id": "9c2f...",
"contractId": "contract_xyz789",
"fromSequence": 1,
"toSequence": 100,
"merkleRoot": "0x...",
"lastReceiptHash": "0x...",
"teeMeasurement": "0x...",
"teeSignature": "0x...",
"data": { "successCount": 94, "providerErrorCount": 3 },
"checkpointedAt": "2026-08-25T21:00:00Z",
"createdAt": "2026-08-25T21:00:01Z"
}
}
{
"error": {
"code": "forbidden",
"message": "Only the contract's matched worker may submit a checkpoint"
}
}
{
"error": {
"code": "conflict",
"message": "fromSequence must be 101 — checkpoints must be gapless and cannot be resubmitted"
}
}
Contracts
Submit Checkpoint
Report periodic progress on a continuous-delivery contract without ending it.
POST
/
v1
/
contracts
/
{id}
/
checkpoint
curl -X POST https://api.opencontract.io/v1/contracts/contract_xyz789/checkpoint \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"fromSequence": 1,
"toSequence": 100,
"merkleRoot": "0x...",
"lastReceiptHash": "0x...",
"teeMeasurement": "0x...",
"teeSignature": "0x...",
"checkpointedAt": "2026-08-25T21:00:00Z",
"data": { "successCount": 94, "providerErrorCount": 3 }
}'
{
"data": {
"id": "9c2f...",
"contractId": "contract_xyz789",
"fromSequence": 1,
"toSequence": 100,
"merkleRoot": "0x...",
"lastReceiptHash": "0x...",
"teeMeasurement": "0x...",
"teeSignature": "0x...",
"data": { "successCount": 94, "providerErrorCount": 3 },
"checkpointedAt": "2026-08-25T21:00:00Z",
"createdAt": "2026-08-25T21:00:01Z"
}
}
{
"error": {
"code": "forbidden",
"message": "Only the contract's matched worker may submit a checkpoint"
}
}
{
"error": {
"code": "conflict",
"message": "fromSequence must be 101 — checkpoints must be gapless and cannot be resubmitted"
}
}
Must be called by the contract’s matched
worker — any other caller is rejected. Only valid while status is matched. Unlike Submit Delivery, this never changes status — a contract can receive any number of checkpoints while matched; only a final Submit Delivery call moves it to under-review.fromSequence/toSequence ranges must be gapless across a contract’s checkpoints — the first must start at 1, and each later one must start exactly where the previous left off. checkpointedAt must strictly increase. Both are rejected with 409 otherwise — this is what prevents a checkpoint from ever being silently skipped, replayed, or reordered.
teeMeasurement/teeSignature/merkleRoot/lastReceiptHash are stored as provided but not yet cryptographically verified — see Periodic checkpoint for what’s real today versus planned.
Path Parameters
string
required
The contract ID.
Request Body
integer
required
Start of this checkpoint’s receipt range. Must equal the previous checkpoint’s
toSequence + 1, or 1 for the first checkpoint.integer
required
End of this checkpoint’s receipt range. Must be >=
fromSequence.string
required
Merkle root over the receipts in this range.
string
required
Hash of the last receipt in this range, extending the per-call hash chain.
string
required
Code measurement of the TEE that produced this checkpoint.
string
required
TEE signature over this checkpoint.
string
required
ISO 8601 time this checkpoint was produced. Must be strictly after the previous checkpoint’s.
object
required
Application-specific cumulative metrics for this range (e.g. TokenSwap’s
cumulativeInputTokens, successCount, providerErrorCount). Stored as-is; not validated against any shape at this level.Response
Returns the created checkpoint.curl -X POST https://api.opencontract.io/v1/contracts/contract_xyz789/checkpoint \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"fromSequence": 1,
"toSequence": 100,
"merkleRoot": "0x...",
"lastReceiptHash": "0x...",
"teeMeasurement": "0x...",
"teeSignature": "0x...",
"checkpointedAt": "2026-08-25T21:00:00Z",
"data": { "successCount": 94, "providerErrorCount": 3 }
}'
{
"data": {
"id": "9c2f...",
"contractId": "contract_xyz789",
"fromSequence": 1,
"toSequence": 100,
"merkleRoot": "0x...",
"lastReceiptHash": "0x...",
"teeMeasurement": "0x...",
"teeSignature": "0x...",
"data": { "successCount": 94, "providerErrorCount": 3 },
"checkpointedAt": "2026-08-25T21:00:00Z",
"createdAt": "2026-08-25T21:00:01Z"
}
}
{
"error": {
"code": "forbidden",
"message": "Only the contract's matched worker may submit a checkpoint"
}
}
{
"error": {
"code": "conflict",
"message": "fromSequence must be 101 — checkpoints must be gapless and cannot be resubmitted"
}
}
List Checkpoints
GET /v1/contracts/{id}/checkpoints
This endpoint is public — no API key required. Returns every checkpoint for the contract, ordered oldest first.
curl https://api.opencontract.io/v1/contracts/contract_xyz789/checkpoints
{
"data": [
{
"id": "9c2f...",
"contractId": "contract_xyz789",
"fromSequence": 1,
"toSequence": 100,
"merkleRoot": "0x...",
"lastReceiptHash": "0x...",
"teeMeasurement": "0x...",
"teeSignature": "0x...",
"data": { "successCount": 94, "providerErrorCount": 3 },
"checkpointedAt": "2026-08-25T21:00:00Z",
"createdAt": "2026-08-25T21:00:01Z"
}
]
}