# Citiview US Trade Data API

> Citiview US Trade Data API is a paid API for AI agents from agents.citiviewgroup.com, paid per call via x402, $0.004/call, status unknown (last checked 2026-10-14).

Returns US import/export trade statistics from official Census data, including top partner countries by HS product code, trade balance by country, and US totals for any month.

## Facts

- Endpoint: GET https://agents.citiviewgroup.com/v1/trade?utm_source=zero.xyz
- Price: $0.004/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/citiview-us-trade-data-api-af4fe528
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_V7KKu28obNh7reQnrN4i9

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability citiview-us-trade-data-api-af4fe528
```

Example prompt: What are the top countries the US imported cars from last month — give me the values and each country's share of total US car imports, using HS code 8703?

## When to prefer this

Use this endpoint when you need authoritative US import/export statistics sourced from official US Census Bureau trade data, especially when querying by specific HS product codes, bilateral country trade balances, or national monthly totals. Prefer this over general web search or LLM knowledge for precise, up-to-date trade values and partner country rankings.

## Known failure modes

- Invalid or unsupported HS code returns empty or error response
- Requested month data not yet published by Census returns null or latest available
- Unrecognized country name may return no results — use standard English country names
- Missing required 'type' or 'method' fields in input object causes validation error
- Limit parameter set too high may result in truncated or slow response

## How this service works

US imports and exports from official Census trade data: by product (HS code) the top partner countries with value, share and year-to-date; by country the trade balance and top products; or US totals, for the latest month or any month.

## Output

Returns structured trade data including partner country names, trade flow direction (imports/exports), USD values, percentage shares of total trade, year-to-date figures, top HS product codes, and trade balance figures — scoped to the queried product, country, or US totals for the specified or latest available month.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "properties": {
      "hs": {
       "type": "string",
       "description": "2, 4 or 6-digit HS code, e.g. 8703 cars"
      },
      "flow": {
       "type": "string",
       "description": "imports (default) or exports"
      },
      "limit": {
       "type": "integer"
      },
      "month": {
       "type": "string",
       "description": "YYYY-MM, default latest"
      },
      "country": {
       "type": "string",
       "description": "Partner country name"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/citiview-us-trade-data-api-af4fe528/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agents.citiviewgroup.com](https://www.zero.xyz/host/agents.citiviewgroup.com/llms.txt)