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

# Governed Fetch (SSAR)

> Main governed request endpoint — the SSAR pipeline

The primary endpoint for governed HTTP requests. Accepts the same contract as the `governed_fetch` MCP tool.

## Request

```http theme={null}
POST /v1/ssar/fetch
Authorization: Bearer <AXON_DECISION_API_KEY>
Content-Type: application/json
```

### Required Fields

| Field | Type | Description |
| :- | :- | :- |
| `url` | string | Target URL to fetch |
| `intent` | string | Business reason for the request |

### Optional Fields

| Field | Type | Description |
| :- | :- | :- |
| `method` | string | `GET`, `POST`, `PUT`, `DELETE` (default `GET`) |
| `headers` | object | Custom headers to send |
| `body` | any JSON value | Request body |
| `timeout_ms` | number | Request timeout |
| `idempotency_key` | string | Deduplication key |
| `task_id` | string | Task identifier. Strongly recommended for every caller. If omitted, the REST route synthesizes `legacy:<idempotency_key>`; mandates with `require_task_metadata=true` reject that fallback. |
| `agent_id` | string | Agent identifier |
| `employee_id` | string | Employee identifier |
| `justification` | string | Human-readable justification |
| `expected_output_type` | string | `table`, `pdf`, `json`, `citations`, `other` |
| `cost_expectation_min_usdc` | number | Expected minimum cost |
| `cost_expectation_max_usdc` | number | Expected maximum cost |
| `evidence_hashes` | array | Supporting evidence |
| `approval_token` | string | Approval token from `check_approval_status` or `POST /v1/approvals/:id/consume` |
| `wallet_id` | string | Specific wallet to use |

### Example Request

```bash theme={null}
curl -X POST http://127.0.0.1:3030/v1/ssar/fetch \
  -H "Authorization: Bearer $AXON_DECISION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.statista.com/v1/reports/123",
    "intent": "Fetching market size data for Q1 strategy report",
    "task_id": "task-001",
    "wallet_id": "<POCKET_WALLET_ID>",
    "idempotency_key": "statista-report-123-20260301"
  }'
```

## Response

### Success response

Returned only when AXON either completes the request without a 402, or successfully settles and retries the paid request.

### Fields

| Field | Type | Description |
| :- | :- | :- |
| `status` | string | HTTP status from the upstream provider |
| `data` | any | Response body from the provider |
| `payment` | object | Payment details (always present) |
| `budget` | object | Current budget snapshot |
| `decision` | object | Decision metadata |
| `transaction_id` | string | When a payment transaction exists |
| `receipt_id` | string | When payment settles |
| `warnings` | array | Risk or provider warnings |

### Payment Object

| Field | Description |
| :- | :- |
| `required` | Whether the upstream returned 402 |
| `settled` | Whether payment was completed |
| `settlement_status` | `no_payment`, `authorized`, `pending_receipt`, `failed` |
| `amount` | Payment amount in USDC |
| `asset` | Payment asset |
| `network` | Chain identifier |
| `tx_hash` | On-chain transaction hash |

### Decision Object

| Field | Description |
| :- | :- |
| `decision_id` | Unique decision identifier |
| `outcome` | `approved` or `throttled` in a success response |
| `reason_code` | Machine-readable reason |
| `reason_text` | Human-readable explanation |
| `risk_score` | Computed risk score |
| `warnings` | Optional warning codes such as `LOW_ALIGNMENT_SCORE` |

### Error responses

Approval, policy, and provider failures are returned as structured error envelopes rather than success payloads.

* `APPROVAL_REQUIRED`: human approval required. The error details include `approval_request_id`.
* `REJECTED_POLICY`, `REJECTED_LIQUIDITY`, `REJECTED_NETWORK`, `INTENT_MISMATCH`: deterministic or scoring denial.
* `PROVIDER_UNVERIFIED`, `PAYMENT_FAILED`, `SETTLEMENT_FAILED`, `REQUEST_TIMEOUT`, `CIRCUIT_OPEN`: provider or settlement failures.

## Behavior

1. If the upstream response is not `402`, AXON returns the provider response without payment
2. On `402`, AXON evaluates deterministic + risk stages, then either:
   * Signs payment and retries the request
   * Escalates or denies with a structured error
3. When retrying after `APPROVAL_REQUIRED`, send the same URL, method, and body together with `approval_token`. Approval matching is bound to that original request context.
4. Call `read_spending_policy` first in a new session to understand the active mandate


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.