> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chance.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Verification request

> Fields for POST /api/v1/intent and the MCP verify_intent tool, and every response shape.

`POST /api/v1/intent` and the MCP tool `verify_intent` take the same fields and run the same pipeline. How the fields are used: [Verification](/concepts/verification).

## Fields

<ResponseField name="intent" type="string" required>
  The rules the action must satisfy. Must be non-empty after trimming.
</ResponseField>

<ResponseField name="action" type="string | object" required>
  The proposed action. A non-empty string is judged as written. An object is classified by a venue adapter when one matches (`mode: "structured"`) and otherwise judged as JSON (`mode: "semantic"`).
</ResponseField>

<ResponseField name="venue" type="string">
  The adapter to use. Ids: `hyperliquid`, `limitless`, `polymarket`, `dimes`, `myriad`, `orderly`, `derive`, `lifi`, `meow`, `liquid`, `robinhood`, `x402`, `agentcards`, `uniswap`, `solana`, `starknet`, `alchemy`.

  * **HTTP:** any string. It is lowercased, stripped of punctuation and matched against the ids, aliases and id prefixes. An unknown value is ignored without an error, and object actions fall back to structural detection.
  * **MCP:** an enum of the ids above plus `evm` (an alias for `alchemy`). Any other value fails schema validation.

  Omit it to let an object action be detected from its shape.
</ResponseField>

<ResponseField name="context" type="object">
  Facts for the judge, shown to it as JSON under `CONTEXT`.
</ResponseField>

<ResponseField name="context.reference" type="object">
  `{ source?: string, excerpt: string }`: the platform's own documentation for the tool being called. The ChanceBot desk sends this. It is taken out of `CONTEXT` and shown to the judge in a fenced `REFERENCE` block, introduced as third-party background that may be wrong, never changes the intent, never authorizes the action, and whose instructions are ignored.

  * `excerpt` must be a non-empty string. It is trimmed, fence markers are removed, and it is cut at 4,000 characters with `[…]` appended.
  * `source` is trimmed, fence markers are removed, and it is cut at 300 characters.
  * A `reference` of any other shape stays in `CONTEXT` as ordinary data.
</ResponseField>

<ResponseField name="preset" type="string" default="generic">
  HTTP only. The judge prompt. Omit it. An unknown value falls back to `generic`.
</ResponseField>

## Example

```bash theme={null}
curl -X POST https://harness.chance.cc/api/v1/intent \
  -H "x-api-key: $CHANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Buy liquid US large-cap stocks only. Max $500 per order. No options, no margin.",
    "venue": "robinhood",
    "action": {
      "name": "place_equity_order",
      "arguments": { "symbol": "AAPL", "side": "buy", "type": "market", "dollar_amount": "450" }
    },
    "context": {
      "aaplLastPrice": 228.40,
      "reference": {
        "source": "Robinhood agentic trading docs: place_equity_order",
        "excerpt": "place_equity_order submits an equity order from the Agentic account. dollar_amount sizes a market order in USD. quantity sizes it in shares."
      }
    }
  }'
```

## Response: `POST /api/v1/intent`

Status `201`.

<ResponseField name="id" type="string">
  Verification id (UUID).
</ResponseField>

<ResponseField name="requestHash" type="string">
  Per-run identifier, 0x and 32 bytes. Not a hash of the payload. Also accepted by the GET.
</ResponseField>

<ResponseField name="status" type="string">
  Always `COMPLETED`.
</ResponseField>

<ResponseField name="verdict" type="string | null">
  `ALLOW`, `BLOCK`, `ESCALATE` or `null`. Execute only on `ALLOW`.
</ResponseField>

<ResponseField name="reasoning" type="string | null">
  The judge's decisive reason.
</ResponseField>

<ResponseField name="mode" type="string">
  `structured` or `semantic`.
</ResponseField>

<ResponseField name="venue" type="string | null">
  The adapter used.
</ResponseField>

<ResponseField name="actionFamily" type="string | null">
  `order`, `margin`, `withdrawal`, `transfer`, `staking`, `vault`, `position`, `swap`, `payment`, `subaccount`, `permission` or `unknown`. `null` without a venue.
</ResponseField>

<ResponseField name="actionType" type="string | null">
  The venue's own action name, when the classifier found one.
</ResponseField>

<ResponseField name="proof" type="object">
  `transcriptRoot`, `outputHash`, `signature`, `judge`, `attested`, `anchorTx`, `anchorVerified`, `transcriptUri`, `explorerTx`. See [Receipts](/concepts/proofs#receipt-fields).
</ResponseField>

<ResponseField name="creditsRemaining" type="integer">
  Balance after this call.
</ResponseField>

## Response: `verify_intent`

A text result: the verdict, the reasoning, a proof summary, the verification id and the balance, followed by a fenced JSON block. The JSON has the same fields as the HTTP response except `actionType`.

## Response: `GET /api/v1/intent/{id}`

`{id}` is the verification `id` or its `requestHash`. It finds any verification on the account, including those behind escrow proposals and dashboard runs. Status `200`.

| Field | |
| - | - |
| `id`, `requestHash`, `status`, `verdict`, `reasoning` | As above. |
| `proof` | `transcriptRoot`, `outputHash`, `signature`, `judge`, `attested`, `anchorTx`, `anchorStatus` (`verified`, `pending` or `skipped`). No `anchorVerified`, `transcriptUri` or `explorerTx`. |
| `createdAt` | ISO timestamp. |

There is no `mode`, `venue`, `actionFamily`, `actionType` or `creditsRemaining`.

## Response: `get_verification`

The MCP tool takes `id` (the verification id or `requestHash`) and returns the GET fields, plus `proof.transcriptUri` and `proof.explorerTx`, as text and a JSON block. Free.

## Errors

| Surface | Status | `error` | When |
| - | - | - | - |
| HTTP | `400` | `invalid JSON body` | The body does not parse. |
| HTTP | `400` | `intent is required` | `intent` is missing or blank. |
| HTTP | `400` | `action is required` | `action` is missing, null or a blank string. |
| HTTP | `401` | `missing API key (send x-api-key)` | No key. |
| HTTP | `401` | `invalid or revoked API key` | Unknown or revoked key. |
| HTTP | `402` | `out_of_credits` | No credits. See [Credits](/concepts/credits#running-out). |
| HTTP | `404` | `not found` | GET: no such verification on this account. |
| HTTP | `502` | `verification_failed` | The run failed. The credit is refunded. |
| MCP | | `intent is required`, `action is required` | Returned as an `isError` result. |
| MCP | | Out-of-credits message | Returned as an `isError` result. |
| MCP | | `verification_failed: …` | Returned as an `isError` result. The credit is refunded. |
| MCP | | `not found` | `get_verification`: no such verification. |

Any error means the action was not verified. Do not execute it.