API endpoints
Co-Signer API
The Co-Signer API is the raw MPC transport used by the client-run Co-Signer. Application backends normally use wallet and transaction endpoints instead of calling these operations directly.
Operations
| Method | Path | Description |
|---|---|---|
GET | /api/v1/co-signer/intents/pending | Read pending DKG or SIGN intents |
POST | /api/v1/co-signer/intents/{intentId}/claim | Claim an intent for one worker |
POST | /api/v1/co-signer/intents/{intentId}/result | Report COMPLETED or FAILED |
POST | /api/v1/co-signer/sessions/{sessionId}/messages | Push an outbound MPC protocol frame |
GET | /api/v1/co-signer/sessions/{sessionId}/messages | Read inbound frames after a sequence |
Required scope for every operation: mpc:raw
Intent lifecycle
Pending intents include intentId, sessionId, correlationId, type, payload, and expiresAt. Claim before processing. The claim operation requires X-Idempotency-Key and may return 409 when another worker already claimed the intent.
Report a terminal result with:
{
"status": "COMPLETED"
}For failures, use FAILED and include errorCode and errorMessage when available. Successful DKG or signing flows may also provide the schema-defined material.
Session messages
Outbound messages contain messageId, protocolSeq, round, Base64 payload, and optional routing fields. protocolSeq supports MPC transport deduplication. Message creation requires X-Idempotency-Key and X-Api-Body-Hash.
Read inbound messages with GET .../messages?afterSeq=<sequence> and persist the highest processed sequence.
Operating rules
- Run one durable Co-Signer service per intended environment.
- Keep the MPC key share and API private key outside the application repository.
- Make claim and message processing idempotent.
- Stop work after
expiresAt. - Monitor pending-intent age, claim conflicts, session progress, and terminal failures.