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

# POST /v1/x402/fetch

> Pay per call with USDC on Base for cited public geospatial facts. No Mireye API key required.

Fetch cited public facts for one US coordinate or street address using an
x402 v2 payment. Each successful call costs **\$0.001 USDC on Base**
(`eip155:8453`), regardless of the number of selected fields. No Mireye account,
API key, prepaid balance, or subscription is required for this route.

Authenticated [`POST /v1/fetch`](https://docs.mireye.ai/api-reference/fetch) remains free. This separate
route lets wallet-equipped agents pay directly without creating an API key.

## Payment flow

1. Send the Fetch request below. Without payment, the API returns `402` with a
   `Payment-Required` header. Decode its base64-encoded x402 v2 JSON to read the
   payment requirements and `extensions.bazaar` discovery metadata. The response
   body is empty JSON (`{}`).
2. An x402 client checks the amount, Base network and recipient, signs a USDC
   payment authorization, and retries the same request with `Payment-Signature`.
3. After verification and successful execution, the payment settles. The `200`
   response contains Fetch data and a `Payment-Response` settlement header.

This request only inspects the payment requirements; it does not pay:

```bash theme={null}
curl -i https://api.mireye.com/v1/x402/fetch \
  -H 'Content-Type: application/json' \
  -d '{"lat":37.7749,"lng":-122.4194,"fields":["elevation"]}'
```

Use an x402 v2 compatible client with a Base wallet funded with USDC to complete
the paid retry. A Mireye API key does not replace the payment on this route.

## Data and limits

The request schema, US coverage, field selectors, presets, response provenance,
address handling and capacity limits match [Fetch](https://docs.mireye.ai/api-reference/fetch.md).
Parcel identity, ownership, boundaries and licensed parcel-derived fields are
excluded. Use the authenticated [Enrich](https://docs.mireye.ai/api-reference/enrich.md) API for those.

Read `partial_failures` and each field's `status`: a successful Fetch response
can contain absent or failed fields and still costs the fixed call price.
HTTP error responses do not proceed to settlement. Failed settlement withholds
the data response.

## Errors and retries

| HTTP | Meaning | Action |
| - | - | - |
| `402` | Payment is missing, invalid, or could not settle. | Read the x402 requirements or settlement result. Correct the payment before retrying. |
| `400` / `422` | The paid request has invalid fields, location or body. | Correct the request; the failed execution is not settled. |
| `429` | Fetch capacity is busy. | Respect `Retry-After`; the failed execution is not settled. |
| `503` with `x402_unavailable` | The payment service is unavailable. | Retry later; no payment was accepted by this gate. |

The account-wallet `Idempotency-Key`, `max_cost_usd` and `/v1/operations` recovery
flow do not apply here. Configure spending limits in your x402 client. If a
response is lost after signing, inspect the payment outcome before authorizing
a new payment; a new authorization can create a separate charge.


## OpenAPI

````yaml POST /v1/x402/fetch
openapi: 3.1.0
info:
  description: >-
    Provenance-tagged geospatial data for US coordinates. POST /v1/fetch for
    deterministic field values (POST /v1/fetch/batch for up to 25 locations at
    once); POST /v1/ask for natural-language Q&A; GET /v1/meta/fields for the
    catalog.
  title: Mireye Earth
  version: 0.18.0
servers:
  - description: Production
    url: https://api.mireye.com
security: []
paths:
  /v1/x402/fetch:
    post:
      summary: Fetch cited geospatial facts with an x402 payment
      description: >-
        Agent-native Fetch endpoint. Pay $0.001 USDC on Base per call; no Mireye
        API key is required. The request and response match POST /v1/fetch. An
        unpaid request returns 402 with Payment-Required and Bazaar discovery
        metadata. Retry with Payment-Signature using an x402 v2 client.
        Successful responses include Payment-Response; inspect partial_failures.
      operationId: x402_fetch_v1_x402_fetch_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: Successful Response
        '402':
          description: x402 payment required, invalid, or settlement failed
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '503':
          description: x402 payment service unavailable
components:
  schemas:
    FetchRequest:
      properties:
        address:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Address
        fields:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Fields
        lat:
          anyOf:
            - type: number
            - type: 'null'
          title: Lat
        lng:
          anyOf:
            - type: number
            - type: 'null'
          title: Lng
        preset:
          anyOf:
            - enum:
                - terrain
                - flood_risk
                - wildfire_underwrite
                - land_cover
                - site_selection
                - building_lookup
                - points_of_interest
                - utilities
                - boundaries
                - solar_siting
                - wind_siting
                - storage_siting
                - data_center_siting
                - grid_interconnect
                - natural_hazard
              type: string
            - type: 'null'
          title: Preset
      title: FetchRequest
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object

````