POST

AI wallet control

Dry run policy evaluation

/api/v2/ai-wallets/{binding_id}/intent-evaluations

AUTHENTICATIONBearer token · ai-wallets:evaluateService ownercore-ai-wallet-controlContract sourceOpenAPISTATUSProduction listed

Purpose and usage

What this endpoint does

Evaluate a typed native-asset action without creating an intent, reservation, event, transaction, signature, approval, or broadcast.

When to use it

Call this when a wallet, treasury, custody, or governed agent workflow needs to apply the documented dry-run policy evaluation 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

Evaluates dry-run policy evaluation without creating an intent, reservation, approval, signature, transaction, broadcast, or settlement side effect.

WHY IT MATTERS

Gives people and agents a contract-backed way to advance dry-run policy evaluation.
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 binding_id (path), type (body), asset (body), amount (body), destination (body) exactly as defined by the live contract.
Resolve the active workspace, network, wallet lifecycle, and applicable custody policy before relying on this result.

WHAT TO DO NEXT

Re-read dry-run policy evaluation 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 dry-run policy evaluation only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Supply the required binding_id (path), type (body), asset (body), amount (body), destination (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.

AI WALLET AUTHORITY BOUNDARY

Implemented reads expose bearer-derived workspace projections, exact policy versions and commitments, independent native-asset budgets, retained decisions, and execution-readiness evidence. POLICY_APPROVED is not transaction construction, signing, broadcast, confirmation, or settlement. The implemented intent-evaluation route is a dry run: it creates no intent, reservation, event, approval, transaction, signature, or broadcast. Any lifecycle, policy, retained-intent, cancellation, or execution operation marked planned is non-executable and must not be registered as an agent tool.

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 the ai-wallets:evaluate scope.EXAMPLEBearer hc_live_…

binding_idpathRequired

32-character lowercase hexadecimal UUIDAI wallet binding visible in the authenticated workspace.EXAMPLEa1b2c3d4e5f6471890abcdeffedcba09

X-Request-IDheaderOptional

stringOptional caller correlation value. The gateway returns the effective request identifier.EXAMPLEagent-run-20260901-0042

typebodyRequired

TRANSFER | TRADE | CONTRACT_CALL | RECURRING_PAYMENTTyped action mapped to one least-privilege wallet capability.EXAMPLETRANSFER

assetbodyRequired

uppercase native asset code · 2–24Asset covered by one exact policy budget envelope.EXAMPLEDHYBRID

amountbodyRequired

positive decimal stringNative-unit amount. JSON numbers, exponent notation, zero, and negative values are rejected.EXAMPLE25.00000000

destinationbodyRequired

{ type, id }Exact destination namespace and identifier checked against the committed allowlist.EXAMPLE{ type: ADDRESS, id: dhyb1approveddestination… }

rationalebodyOptional

{ schema, summary, explanation, expected_outcome, reference } | nullOptional explanation for the preview. It is not retained and grants no authority.

purposebodyOptional

string | nullOptional concise purpose used when rationale is omitted.EXAMPLEPreview treasury allocation

REQUEST

JSON body example

{
  "type": "TRANSFER",
  "asset": "DHYBRID",
  "amount": "25.00000000",
  "destination": {
    "type": "ADDRESS",
    "id": "dhyb1approveddestination…"
  },
  "purpose": "Preview treasury allocation"
}

RESPONSES

Status and payload examples

200Side-effect-free policy decision and projected native-unit budget.Mutation completed · JSON RESPONSE+

{
  "dry_run": true,
  "state": "POLICY_APPROVED",
  "decision_code": "POLICY_ALLOWED",
  "capability": "wallet:quote",
  "asset_code": "DHYBRID",
  "amount": "25.00000000",
  "policy_uuid": "104db2e6b7b842bb8ab733e3b6e74870",
  "policy_version": 4,
  "policy_commitment": "4c2ac3d7…",
  "budget_before": {
    "accounting_model": "PER_ASSET_NATIVE_UNITS_V1",
    "asset_code": "DHYBRID",
    "currency": "DHYBRID",
    "max_single_amount": "100.00000000",
    "daily_limit": "500.00000000",
    "daily_committed": "125.00000000",
    "daily_remaining": "375.00000000",
    "monthly_limit": "5000.00000000",
    "monthly_committed": "825.00000000",
    "monthly_remaining": "4175.00000000",
    "active_intent_count": 3
  },
  "projected_budget": {
    "daily_committed": "150.00000000",
    "monthly_committed": "850.00000000",
    "asset_code": "DHYBRID"
  },
  "execution_created": false,
  "reservation_created": false,
  "event_created": false
}

INTEGRATION DECISION

CALLER ACTION: Accept the returned representation or receipt, then re-read dry-run policy evaluation using the canonical identifier returned by this operation.
RETRY SAFETY: Do not repeat a successful mutation merely to confirm it. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
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 JSON body is malformed.Request must change · JSON RESPONSE+

{
  "code": "invalid_json",
  "message": "The JSON body is malformed."
}

INTEGRATION DECISIONinvalid_json

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Re-read the wallet, intent, reservation, and transaction status on the same network; compare policy version, nonce, digest, and terminal receipt before another command.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

401The bearer credential is missing or invalid.Authentication required · JSON RESPONSE+

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

INTEGRATION DECISIONinvalid_credentials

CALLER ACTION: Discard the rejected credential, complete the documented authentication or reassertion flow, and rebuild any request signature with fresh timestamps and nonces.
RETRY SAFETY: Retry only with a newly valid credential and fresh replay-protection values. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Assume the outcome is unknown only when the connection failed after transmission; otherwise authentication failed before domain work. Re-read the wallet, intent, reservation, and transaction status on the same network; compare policy version, nonce, digest, and terminal receipt before another command.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

403The credential lacks ai-wallets:evaluate or is outside the derived workspace.Authority or policy denied · JSON RESPONSE+

{
  "code": "insufficient_scope",
  "message": "The credential lacks ai-wallets:evaluate or is outside the derived workspace."
}

INTEGRATION DECISIONinsufficient_scope

CALLER ACTION: Verify the exact scope, tenant or workspace membership, owner boundary, step-up purpose, feature policy, and resource eligibility. Never broaden authority automatically.
RETRY SAFETY: Do not retry until the missing authority or policy condition has been deliberately resolved with least privilege.
STATE RECONCILIATION: Confirm the caller and resource resolve to the same authority boundary for owner-scoped wallet inventory, custody policy, balances, intents, reservations, transactions, and receipts.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

404The binding is not visible in this workspace.Resource not visible · JSON RESPONSE+

{
  "code": "ai_wallet_binding_not_found",
  "message": "The binding is not visible in this workspace."
}

INTEGRATION DECISIONai_wallet_binding_not_found

CALLER ACTION: Verify the canonical identifier and authenticated owner boundary. A 404 may intentionally conceal a resource outside the caller's authority.
RETRY SAFETY: Do not retry the unchanged identifier repeatedly. Refresh the relevant collection or lookup before choosing another identifier.
STATE RECONCILIATION: Re-read the wallet, intent, reservation, and transaction status on the same network; compare policy version, nonce, digest, and terminal receipt before another command.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

409No active committed policy is available.State reconciliation required · JSON RESPONSE+

{
  "code": "active_policy_required",
  "message": "No active committed policy is available."
}

INTEGRATION DECISIONactive_policy_required

CALLER ACTION: Stop the mutation sequence and fetch the latest authoritative resource, lifecycle state, version, ETag, reservation, or existing idempotency result.
RETRY SAFETY: Retry only after reconciling the conflict. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Re-read the wallet, intent, reservation, and transaction status on the same network; compare policy version, nonce, digest, and terminal receipt before another command.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

422The identifiers or evaluation inputs are invalid.Request must change · JSON RESPONSE+

{
  "code": "invalid_evaluation",
  "message": "The identifiers or evaluation inputs are invalid."
}

INTEGRATION DECISIONinvalid_evaluation

CALLER ACTION: Rebuild the request from the live OpenAPI operation and correct the rejected method, media type, header, parameter, or body field.
RETRY SAFETY: Do not retry the same invalid request. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt.
STATE RECONCILIATION: Compare the submitted values with the documented constraints before another call. Re-read the wallet, intent, reservation, and transaction status on the same network; compare policy version, nonce, digest, and terminal receipt before another command.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

503The authoritative control plane is unavailable and failed closed.Dependency unavailable or outcome uncertain · JSON RESPONSE+

{
  "code": "ai_wallet_control_unavailable",
  "message": "The authoritative control plane is unavailable and failed closed."
}

INTEGRATION DECISIONai_wallet_control_unavailable

CALLER ACTION: Preserve the exact request and treat the outcome as uncertain until authoritative state proves whether it committed.
RETRY SAFETY: Reconcile before retrying. This mutation has no documented idempotent replay contract. Reconcile state before considering another attempt. Use bounded backoff with jitter.
STATE RECONCILIATION: Re-read the wallet, intent, reservation, and transaction status on the same network; compare policy version, nonce, digest, and terminal receipt before another command.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

OPERATIONAL NOTES

Security and lifecycle guarantees

This is a preview only. It creates no intent, reservation, activity event, approval, transaction, signature, execution request, or broadcast.
No Idempotency-Key is required because no state is created. Re-evaluate before consequential use because policy, budget, and velocity state can change.
The gateway derives workspace and principal context from the bearer; callers cannot supply or override either boundary.
Policy approval is evidence of a policy decision only. It is never transaction construction, signing, broadcast, confirmation, settlement, or value-movement authority.
Amounts and limits are exact native-asset decimal strings. Never parse them through binary floating point or aggregate unlike assets.
Private keys, MPC shares, seeds, signing nonces, participant secrets, and credentials are never accepted or returned.

Reference version and availability details

This route is implemented in canonical gateway source and appears in the production OpenAPI snapshot observed 2026-10-02T23:27:55.510Z. Authentication, tenant, feature, venue, and market policy still apply.

Verify the exact production OpenAPI operation Return to the V2 directory