# 2s Trade Flows API

> 2s Trade Flows API is a paid API for AI agents from 2s.io, paid per call via x402, $0.009/call, status unknown (last checked 2026-10-28).

Retrieves UN Comtrade international merchandise trade flow data (imports/exports) by country, year, and commodity code

## Facts

- Endpoint: GET https://2s.io/api/trade/flows?utm_source=zero.xyz
- Price: $0.009/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-28
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/2s-trade-flows-api-ef582592
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_hjSycwdXrnBj8qn_RktyR

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 2s-trade-flows-api-ef582592
```

Example prompt: What were the top 25 goods the US exported to the world in 2022? Pull from UN Comtrade annual data and sort by trade value.

## When to prefer this

Use this endpoint when you need official, ground-truth international trade statistics sourced from UN Comtrade — especially for annual merchandise trade values, weights, and quantities broken down by country pair and HS commodity code. Prefer this over web scraping or unofficial sources when accuracy and citability matter. Best for research, economic analysis, supply chain intelligence, and policy reporting.

## Known failure modes

- Missing required 'reporter' or 'year' parameters returns validation error
- Invalid ISO country code or M49 number returns empty result or upstream error
- Requested year has no data yet due to Comtrade's 6-12 month reporting lag
- Invalid HS commodity code returns empty items array
- limit out of range (>100 or <1) causes schema validation failure
- Upstream Comtrade API unavailable returns error response

## How this service works

Annual international merchandise-trade flows from UN Comtrade (HS classification). Pass reporter (the country whose trade you want; ISO-2/ISO-3 like 'US'/'USA', a UN M49 number, or 'World'), optional partner (counterparty; default World), year (YYYY), flow (export|import), and commodity: 'TOTAL' (all goods, default), a specific HS code ('27', '8703'), or 'AG2'/'AG4'/'AG6' for a top-commodity breakdown at the 2/4/6-digit level. Returns trade value (USD), net weight, quantity, and the HS commodity, sorted by value. Country names are resolved from Comtrade's own reference data.

## Output

Returns an array of trade flow records, each with reporter country, partner country, commodity HS code and description, trade direction (import/export), period, value in USD, net weight in kg, and quantity with unit. Also includes metadata about the query parameters used and source attribution (UN Comtrade license and URL). Total matching row count is provided when available.

## 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",
    "queryParams"
   ],
   "properties": {
    "type": {
     "const": "http"
    },
    "method": {
     "const": "GET"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "reporter",
      "year"
     ],
     "properties": {
      "flow": {
       "enum": [
        "export",
        "import"
       ],
       "type": "string",
       "default": "export",
       "description": "Trade direction from the reporter's perspective. Default export."
      },
      "year": {
       "type": "string",
       "description": "Calendar year (YYYY). Comtrade annual data typically lags ~6-12 months."
      },
      "limit": {
       "type": "integer",
       "default": 25,
       "maximum": 100,
       "minimum": 1,
       "description": "Max rows to return (1-100), sorted by trade value desc. Default 25."
      },
      "partner": {
       "type": "string",
       "default": "World",
       "maxLength": 40,
       "minLength": 2,
       "description": "Partner/counterparty country (same formats). Default \"World\" (all partners aggregated)."
      },
      "reporter": {
       "type": "string",
       "maxLength": 40,
       "minLength": 2,
       "description": "Reporting country: ISO-2/ISO-3 (\"US\"/\"USA\"), UN M49 number, or \"World\"."
      },
      "commodity": {
       "type": "string",
       "default": "TOTAL",
       "maxLength": 8,
       "minLength": 2,
       "description": "\"TOTAL\" (all goods, default), a specific HS code (\"27\", \"8703\"), or \"AG2\"/\"AG4\"/\"AG6\" for a top-commodity breakdown."
      }
     },
     "additionalProperties": false
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "schema": {
  "type": "object",
  "required": [
   "ok",
   "items",
   "total",
   "source"
  ],
  "properties": {
   "ok": {
    "enum": [
     true
    ],
    "type": "boolean"
   },
   "meta": {
    "type": "object",
    "required": [
     "query"
    ],
    "properties": {
     "query": {
      "type": "object",
      "required": [
       "reporter",
       "reporterCode",
       "partner",
       "partnerCode",
       "year",
       "flow",
       "commodity"
      ],
      "properties": {
       "flow": {
        "type": "string"
       },
       "year": {
        "type": "string"
       },
       "partner": {
        "type": "string"
       },
       "reporter": {
        "type": "string"
       },
       "commodity": {
        "type": "string"
       },
       "partnerCode": {
        "type": "integer"
       },
       "reporterCode": {
        "type": "integer"
       }
      },
      "additionalProperties": false
     }
    },
    "additionalProperties": false
   },
   "items": {
    "type": "array",
    "items": {
     "type": "object",
     "required": [
      "reporter",
      "reporterIso",
      "partner",
      "partnerIso",
      "flow",
      "period",
      "commodityCode",
      "commodity",
      "valueUsd",
      "netWeightKg",
      "quantity",
      "quantityUnit"
     ],
     "properties": {
      "flow": {
       "type": "string",
       "nullable": true
      },
      "period": {
       "type": "string",
       "nullable": true
      },
      "partner": {
       "type": "string",
       "nullable": true
      },
      "quantity": {
       "type": "number",
       "nullable": true
      },
      "reporter": {
       "type": "string",
       "nullable": true
      },
      "valueUsd": {
       "type": "number",
       "nullable": true
      },
      "commodity": {
       "type": "string",
       "nullable": true
      },
      "partnerIso": {
       "type": "string",
       "nullable": true
      },
      "netWeightKg": {
       "type": "number",
       "nullable": true
      },
      "reporterIso": {
       "type": "string",
       "nullable": true
      },
      "quantityUnit": {
       "type": "string",
       "nullable": true
      },
      "commodityCode": {
       "type": "string",
       "nullable": true
      }
     },
     "additionalProperties": false
    }
   },
   "total": {
    "type": "integer",
    "nullable": true,
    "description": "Total matching rows upstream; null when unknown."
   },
   "s
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/2s-trade-flows-api-ef582592/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from 2s.io](https://www.zero.xyz/host/2s.io/llms.txt)