DOCUMENTATIONv2

POST

Digital assets

Reconcile market delivery

/api/v2/asset-market-orders/{order_uuid}/reconciliations

AUTHENTICATIONBearer token · assets:reconcileAUTHORITATIVE OWNERasset-registry-serviceCONTRACT AUTHORITYCapability registry · plannedSTATUSPlanned · not executable

PLANNING CONTRACT · NOT CALLABLE

This page describes intended capability and integration boundaries so people and agents can prepare safely. Do not send this request or register it as an executable tool. Wait until the capability registry marks it implemented-contract, then re-fetch the deployed OpenAPI document and build the request from that machine contract.

PURPOSE + BUSINESS CONTEXT

Planned capability: verify one Commerce-owned payment confirmation against an asset-market order and, only when every immutable term matches, request atomic delivery of the order's reserved items.

WHEN THIS CALL IS USEFUL

Do not call or register this operation as an executable agent tool yet. Use this page to plan the future reconcile market delivery workflow; enable it only after the status becomes implemented-contract and the exact operation appears in deployed OpenAPI.

OUTCOME · Planned · Create or advance

What changes

None today: this route is not executable. Its intended behavior is: no executable public reconciliation exists. A future DELIVER_IF_MATCHED transition would atomically debit seller holdings, credit buyer holdings, finalize reserved items, and retain linked payment and delivery proofs only after every immutable term matches.

WHY IT MATTERS

Lets people and agents prepare for reconcile market delivery without falsely presenting roadmap scope as a live capability.
Gives people and agents a contract-backed way to advance reconcile market delivery.
Lets clients verify asset identity and provenance without treating display metadata or portfolio visibility as issuance or trading authority.

ISOLATION + AUTHORITY

Issuer, collection, asset, mint, proof, owner, network, supply, metadata, custody, marketplace, and trading boundaries remain distinct. Reading an asset or proof cannot issue, mint, transfer, list, value, or trade it; current trading and matching controls remain frozen unless separately approved. This planning record grants no runtime authority, and only deployed OpenAPI can define an executable public contract.

BEFORE YOU CALL

First confirm that this operation is marked implemented-contract and exists in the currently deployed OpenAPI document; until then, no production request is valid.
Its capability-registry profile is provisional integration guidance, not an executable request schema.
Authenticate at the documented boundary: bearer+scope.
Treat the proposed order_uuid (path), payment_confirmation_uuid (body), payment_confirmation_commitment (body), expected_order_state (body), expected_order_version (body), reconciliation_mode (body), step_up_token (body) as planning input only; re-generate the request from deployed OpenAPI before making a call.
Use one Idempotency-Key only for retries of the same byte-equivalent logical mutation.
Resolve the canonical asset or collection identifier, issuer, network, lifecycle, supply, and required proof freshness.

WHAT TO DO NEXT

Keep this operation disabled in clients, agents, SDKs, and workflow automation while it remains planned-contract.
Use the stated owner, lifecycle, authority boundary, and provisional reconcile market delivery profile to prepare requirements and conformance tests without sending a request.
Monitor the capability registry for implemented-contract, then re-fetch deployed OpenAPI and validate its exact security, parameters, schemas, responses, and agent metadata before enabling the integration.

AGENT GUIDANCE

Never call this planned contract, include it in an executable tool registry, or infer runtime availability from this readable page.
Its capability-registry profile is provisional integration guidance, not an executable request schema.
Use reconcile market delivery only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Treat the proposed order_uuid (path), payment_confirmation_uuid (body), payment_confirmation_commitment (body), expected_order_state (body), expected_order_version (body), reconciliation_mode (body), step_up_token (body) as planning input only; re-generate the request from deployed OpenAPI before making a call.
Distinguish declared metadata, issuer identity, collection membership, mint evidence, supply state, ownership or custody, market listing, price, transfer, and finality.
After a timeout or conflict, read authoritative state before deciding whether an equivalent retry is safe.
When implementation lands, discard generated requests based on this planning record and rebuild them from the deployed OpenAPI operation.

MACHINE CONTRACT

This operation is a non-executable planning contract. Its capability-registry record defines the intended owner, parameters, responses, and integration boundary until an implemented Rust OpenAPI operation replaces it.

EXTENDED INTEGRATION GUIDANCE

Readable request and response reference

Examples describe the reviewed planning contract and remain non-executable until promoted into OpenAPI.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

Bearer tokenCredential containing the assets:reconcile scope.EXAMPLEBearer hc_live_…

Idempotency-KeyheaderRequired

ASCII string · 1–128Caller-generated key reused for every retry of the same logical mutation.EXAMPLElaunch-treasury-v1-001

Content-TypeheaderRequired

application/jsonSigned mutations accept canonical JSON only.EXAMPLEapplication/json

Content-DigestheaderRequired

RFC 9530 SHA-256 digestDigest of the exact transmitted body bytes.EXAMPLEsha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:

Signature-InputheaderRequired

RFC 9421 signature parametersCovers @method, @path, content-digest, content-type, and idempotency-key; includes keyid, nonce, created, and expires.EXAMPLEsig1=("@method" "@path" "content-digest" "content-type" "idempotency-key");created=1786582800;expires=1786583100;nonce="01J…";keyid="machine-prod"

SignatureheaderRequired

Ed25519 HTTP Message SignatureSignature made by an active public key registered to the authenticated client.EXAMPLEsig1=:base64-signature:

order_uuidpathRequired

identifierOwner-visible asset-market order whose reserved items and payment evidence are reconciled.EXAMPLEasset-order-01

payment_confirmation_uuidbodyRequired

identifierStable confirmation issued by the authoritative Commerce payment owner; callers cannot assert paid state.EXAMPLEpay-confirmation-01

payment_confirmation_commitmentbodyRequired

64-character hexadecimal SHA-256 digestCommitment to the exact signed Commerce confirmation.EXAMPLEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

expected_order_statebodyRequired

PAYMENT_PENDING | PAIDLast state from the owner-visible order. Read an already FULFILLED order instead of replaying delivery.EXAMPLEPAYMENT_PENDING

expected_order_versionbodyRequired

integer · ≥1Optimistic-concurrency version from the latest order projection.EXAMPLE4

reconciliation_modebodyRequired

VERIFY_ONLY | DELIVER_IF_MATCHEDVERIFY_ONLY changes nothing. DELIVER_IF_MATCHED becomes eligible only after every immutable payment and reservation term matches.EXAMPLEVERIFY_ONLY

evidence_referencesbodyOptional

identifier[] · max 20Commitment-safe references to retained Commerce or chain evidence; no raw receipts, customer data, credentials, or secrets.EXAMPLE["commerce-evidence-01"]

step_up_tokenbodyRequired

purpose-bound tokenFresh ASSET_MARKET_ORDER_RECONCILIATION authorization.EXAMPLEhcsu_…

REQUEST

JSON body example

{
  "payment_confirmation_uuid": "pay-confirmation-01",
  "payment_confirmation_commitment": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "expected_order_state": "PAYMENT_PENDING",
  "expected_order_version": 4,
  "reconciliation_mode": "VERIFY_ONLY",
  "evidence_references": [
    "commerce-evidence-01"
  ],
  "step_up_token": "hcsu_…"
}

RESPONSES

Status and payload examples

202Reconciliation accepted; acceptance is not asset delivery.Not executable · JSON RESPONSE+

{
  "reconciliation_uuid": "reconciliation-01",
  "order_uuid": "asset-order-01",
  "mode": "VERIFY_ONLY",
  "status": "ACCEPTED",
  "payment_confirmation_verified": false,
  "differences": [],
  "delivery_requested": false,
  "delivery_completed": false
}

INTEGRATION DECISION

CALLER ACTION: Do not send this request or register it as an executable agent tool. Use the implemented alternatives linked by the module guide.
RETRY SAFETY: Do not retry on a timer. Re-fetch production OpenAPI and proceed only after this exact operation appears there.
STATE RECONCILIATION: No runtime state exists to reconcile for this planning contract. Continue from owner-scoped funding methods, deposit instructions, transfer intents, settlement progress, and delivery receipts through an implemented operation.
ESCALATE WHEN: Escalate when money movement is ambiguous, provider and ledger states disagree, or a destination or asset cannot be proven exact.

400A field, signed header, step-up token, or idempotency key is malformed.Not executable · JSON RESPONSE+

{
  "code": "invalid_reconciliation_request",
  "message": "A field, signed header, step-up token, or idempotency key is malformed."
}

INTEGRATION DECISIONinvalid_reconciliation_request

CALLER ACTION: Do not send this request or register it as an executable agent tool. Use the implemented alternatives linked by the module guide.
RETRY SAFETY: Do not retry on a timer. Re-fetch production OpenAPI and proceed only after this exact operation appears there.
STATE RECONCILIATION: No runtime state exists to reconcile for this planning contract. Continue from owner-scoped funding methods, deposit instructions, transfer intents, settlement progress, and delivery receipts through an implemented operation.
ESCALATE WHEN: Escalate when money movement is ambiguous, provider and ledger states disagree, or a destination or asset cannot be proven exact.

401The bearer credential is invalid.Not executable · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "The bearer credential is invalid."
}

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Do not send this request or register it as an executable agent tool. Use the implemented alternatives linked by the module guide.
RETRY SAFETY: Do not retry on a timer. Re-fetch production OpenAPI and proceed only after this exact operation appears there.
STATE RECONCILIATION: No runtime state exists to reconcile for this planning contract. Continue from owner-scoped funding methods, deposit instructions, transfer intents, settlement progress, and delivery receipts through an implemented operation.
ESCALATE WHEN: Escalate when money movement is ambiguous, provider and ledger states disagree, or a destination or asset cannot be proven exact.

403The principal lacks assets:reconcile, order visibility, or fresh step-up authority.Not executable · JSON RESPONSE+

{
  "code": "reconciliation_forbidden",
  "message": "The principal lacks assets:reconcile, order visibility, or fresh step-up authority."
}

INTEGRATION DECISIONreconciliation_forbidden

CALLER ACTION: Do not send this request or register it as an executable agent tool. Use the implemented alternatives linked by the module guide.
RETRY SAFETY: Do not retry on a timer. Re-fetch production OpenAPI and proceed only after this exact operation appears there.
STATE RECONCILIATION: No runtime state exists to reconcile for this planning contract. Continue from owner-scoped funding methods, deposit instructions, transfer intents, settlement progress, and delivery receipts through an implemented operation.
ESCALATE WHEN: Escalate when money movement is ambiguous, provider and ledger states disagree, or a destination or asset cannot be proven exact.

404The order or Commerce-owned confirmation is not owner-visible.Not executable · JSON RESPONSE+

{
  "code": "reconciliation_resource_not_found",
  "message": "The order or Commerce-owned confirmation is not owner-visible."
}

INTEGRATION DECISIONreconciliation_resource_not_found

CALLER ACTION: Do not send this request or register it as an executable agent tool. Use the implemented alternatives linked by the module guide.
RETRY SAFETY: Do not retry on a timer. Re-fetch production OpenAPI and proceed only after this exact operation appears there.
STATE RECONCILIATION: No runtime state exists to reconcile for this planning contract. Continue from owner-scoped funding methods, deposit instructions, transfer intents, settlement progress, and delivery receipts through an implemented operation.
ESCALATE WHEN: Escalate when money movement is ambiguous, provider and ledger states disagree, or a destination or asset cannot be proven exact.

409Order state or version is stale, payment terms differ, inventory is not reserved, delivery is final, or the idempotency key conflicts.Not executable · JSON RESPONSE+

{
  "code": "reconciliation_conflict",
  "message": "Order state or version is stale, payment terms differ, inventory is not reserved, delivery is final, or the idempotency key conflicts."
}

INTEGRATION DECISIONreconciliation_conflict

CALLER ACTION: Do not send this request or register it as an executable agent tool. Use the implemented alternatives linked by the module guide.
RETRY SAFETY: Do not retry on a timer. Re-fetch production OpenAPI and proceed only after this exact operation appears there.
STATE RECONCILIATION: No runtime state exists to reconcile for this planning contract. Continue from owner-scoped funding methods, deposit instructions, transfer intents, settlement progress, and delivery receipts through an implemented operation.
ESCALATE WHEN: Escalate when money movement is ambiguous, provider and ledger states disagree, or a destination or asset cannot be proven exact.

422Signature, amount, currency, recipient, finality, network, or evidence policy rejected the confirmation.Not executable · JSON RESPONSE+

{
  "code": "payment_confirmation_rejected",
  "message": "Signature, amount, currency, recipient, finality, network, or evidence policy rejected the confirmation."
}

INTEGRATION DECISIONpayment_confirmation_rejected

CALLER ACTION: Do not send this request or register it as an executable agent tool. Use the implemented alternatives linked by the module guide.
RETRY SAFETY: Do not retry on a timer. Re-fetch production OpenAPI and proceed only after this exact operation appears there.
STATE RECONCILIATION: No runtime state exists to reconcile for this planning contract. Continue from owner-scoped funding methods, deposit instructions, transfer intents, settlement progress, and delivery receipts through an implemented operation.
ESCALATE WHEN: Escalate when money movement is ambiguous, provider and ledger states disagree, or a destination or asset cannot be proven exact.

503Commerce, asset-ledger, evidence, or atomic delivery ownership is unavailable; no asset state changes.Not executable · JSON RESPONSE+

{
  "code": "reconciliation_unavailable",
  "message": "Commerce, asset-ledger, evidence, or atomic delivery ownership is unavailable; no asset state changes."
}

INTEGRATION DECISIONreconciliation_unavailable

CALLER ACTION: Do not send this request or register it as an executable agent tool. Use the implemented alternatives linked by the module guide.
RETRY SAFETY: Do not retry on a timer. Re-fetch production OpenAPI and proceed only after this exact operation appears there.
STATE RECONCILIATION: No runtime state exists to reconcile for this planning contract. Continue from owner-scoped funding methods, deposit instructions, transfer intents, settlement progress, and delivery receipts through an implemented operation.
ESCALATE WHEN: Escalate when money movement is ambiguous, provider and ledger states disagree, or a destination or asset cannot be proven exact.

OPERATIONAL NOTES

Security and lifecycle guarantees

This is a reviewed planning contract and is not callable until it appears in the live production OpenAPI document.
Never convert a caller-authored paid, confirmed, amount, currency, buyer, seller, or transaction field into authority. The service resolves and verifies payment_confirmation_uuid at Commerce.
VERIFY_ONLY must change nothing. DELIVER_IF_MATCHED must lock the order and holdings, re-check every item and settlement invariant, then atomically debit seller holdings, credit buyer holdings, finalize items, and retain linked proofs.
HTTP 202 means work was accepted. Re-read the order and verify retained payment and delivery proof commitments before describing fulfillment.

DOCUMENTATION STATUS

This planned contract now defines its public parameters, authorization boundary, replay behavior, responses, and authoritative owner. It remains non-executable until its owner adapter and conformance tests are promoted into the Rust gateway.

Return to the V2 directory ↗