POST

MPC wallet lifecycle

Create network enrollment intent

/api/v2/wallets/enrollments

AUTHENTICATIONBearer token · wallets:writeService ownercustody-serviceContract sourceOpenAPISTATUSProduction listed

Purpose and usage

What this endpoint does

Create one idempotent owner- and workspace-bound enrollment intent on an explicit Hybrid network while keeping customer authorization, 7-of-13 DKG, and activation separate.

When to use it

Call this when a wallet, treasury, custody, or governed agent workflow needs to apply the documented network enrollment intent transition after re-reading the current authoritative state so it can make a custody decision inside the correct owner, workspace, network, and policy boundary.

OUTCOME · Create or advance

What changes

Creates or advances only the network enrollment intent resource described by this contract after authorization, validation, policy, and idempotency gates pass.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance network enrollment intent.
Makes custody state understandable without exposing seeds, shares, nonces, private keys, or other reusable signing material.

ISOLATION + AUTHORITY

The authenticated owner, workspace, network, and wallet policy remain authoritative. A wallet record, policy result, approval, ceremony, or balance never grants another lifecycle stage and cannot substitute for threshold signing or separately owned funding, settlement, publisher, matching, or trading authority.

BEFORE YOU CALL

Authenticate at the documented boundary: bearer+scope.
Supply the required network_id (body) exactly as defined by the live contract.
Use one Idempotency-Key only for retries of the same byte-equivalent logical mutation.
Resolve the active workspace, network, wallet lifecycle, and applicable custody policy before relying on this result.

WHAT TO DO NEXT

Re-read network enrollment intent using the canonical identifier returned by this operation.
Reconcile an ambiguous response with the same idempotency key before attempting another mutation.
Re-read the wallet and policy state before the next governed action, especially after an ambiguous or concurrent result.

AGENT GUIDANCE

Use network enrollment intent only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required network_id (body) exactly as defined by the live contract.
Keep enrollment, activation, policy evaluation, approval, ceremony, signing, submission, confirmation, and settlement as distinct states.
After a timeout or conflict, read authoritative state before deciding whether an equivalent retry is safe.

Contract reference

Use the deployed OpenAPI for exact parameters, schemas and security requirements. The tables below provide integration guidance.

Open this operation in OpenAPI

Request and response

Make the request

Examples illustrate integration intent; the referenced OpenAPI operation and component schemas define the executable shape.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

Bearer tokenCredential containing wallets:write authority.EXAMPLEBearer hc_live_…

Idempotency-KeyheaderRequired

ASCII string · 1–128Caller-generated stable key reused for retries of the same logical mutation.EXAMPLEpost-api-v2-wallets-enrollments-request-001

X-Request-IDheaderOptional

stringOptional caller correlation identifier. The gateway emits the effective value on the response.

Content-DigestheaderRequired

stringRFC 9530 sha-256 digest of the exact transmitted request-body bytes.

Signature-InputheaderRequired

stringRFC 9421 sig1 input covering @method, @path, content-digest, content-type, and idempotency-key, with created, expires, nonce, keyid, and alg=ed25519.

SignatureheaderRequired

stringRFC 9421 sig1 Ed25519 signature made by an active key registered to the bearer client.

acknowledge_activation_is_separatebodyOptional

booleanRequired true only for Mainnet to acknowledge that enrollment does not activate deposits or withdrawals.EXAMPLEfalse

acknowledge_distributed_custodybodyOptional

booleanRequired true only for Mainnet to acknowledge the separate 7-of-13 distributed-custody ceremony.EXAMPLEfalse

network_idbodyRequired

Hybrid control-plane network identifierExact network: hybrid-devnet, hybrid-testnet, or hybrid-mainnet. It is never inferred from an asset or prior enrollment.EXAMPLEhybrid-devnet

REQUEST

JSON body example

{
  "acknowledge_activation_is_separate": true,
  "acknowledge_distributed_custody": true,
  "network_id": "hybrid-devnet"
}

RESPONSES

Status and payload examples

201Enrollment intent recorded. Customer authorization, independent 7-of-13 DKG, chain activation, signing, and broadcast remain separate and ungranted.Mutation completed · JSON RESPONSE+

"example-value"

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then re-read network enrollment intent using the canonical identifier returned by this operation.
RETRY SAFETY: Do not repeat a successful mutation merely to confirm it. For one logical mutation, retain the same Idempotency-Key and byte-equivalent request. Never reuse that key for changed instructions.
STATE RECONCILIATION: Persist returned identifiers, versions, commitments, and receipts. Re-read the wallet, intent, reservation, and transaction status on the same network; compare policy version, nonce, digest, and terminal receipt before another command.

400The request syntax, required metadata, or JSON body is malformed.Request must change · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "the supplied Hybrid credential is invalid"
}