API reference

Base URL https://cetatraders.com. JSON in, JSON out. Amounts are integer minor units with their currency. Also as OpenAPI 3.1.

Account

GET


        /api/v1/status

scope read

Check your key

Connectivity, and what this key is allowed to do. A test key answers its sandbox tenant's organization id and mode: "test".

Request

curl "https://cetatraders.com/api/v1/status" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "mode": "live",
  "name": "Ceta Traders API",
  "organization_id": "5d0e8a3c-2f41-4b7a-9e1d-6c5b4a392817",
  "scopes": [
    "read"
  ],
  "time": "2026-11-14T10:00:00.000000Z",
  "version": "v1"
}

GET


        /api/v1/verification

scope read

Can this key transact?

A key acts for the person who issued it, so it can transact only while Authpermit has that person verified (RAL3). Test keys never transact.

Request

curl "https://cetatraders.com/api/v1/verification" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "can_transact": true,
  "status": "verified"
}

403 ekyc_required The issuer is not verified: reason (ekyc_required | ekyc_pending | ekyc_rejected | ekyc_unavailable), message, verify_url.

Marketplace

GET


        /api/v1/products

scope read

Published products

Search with q, or list published products filtered by channel. Amounts are integer minor units with the currency beside them.

Parameter	In	Type	Description
q	query	string	Full-text search.
channel	query	string	`b2b` or `b2c`.

Request

curl "https://cetatraders.com/api/v1/products?q=…&channel=…" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "count": 1,
  "data": [
    {
      "category": "coffee",
      "channel": "b2b",
      "currency": "EUR",
      "description": "Washed, screen 16+, crop 2026.",
      "id": "6f1c2a9e-4b1d-4a43-9c55-1d2f4e8a7b10",
      "image_url": "https://cetatraders.com/files/ceta-uploads/products/cof-ara-60.jpg",
      "min_order_qty": 10,
      "price_cents": 42000,
      "sku": "COF-ARA-60",
      "title": "Arabica green coffee, 60 kg bag",
      "vendor": {
        "id": "0b6f3c52-8c1e-4f7a-a2b9-3e5d7c9a1f22",
        "name": "Lisboa Roasters Lda"
      }
    }
  ]
}

GET


        /api/v1/vendors

scope read

Vendors

The vendors on the B2B marketplace.

Request

curl "https://cetatraders.com/api/v1/vendors" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "count": 1,
  "data": [
    {
      "country": "PT",
      "id": "0b6f3c52-8c1e-4f7a-a2b9-3e5d7c9a1f22",
      "name": "Lisboa Roasters Lda",
      "status": "active"
    }
  ]
}

GET


        /api/v1/orders

scope read

Your organization's orders

Tenant-scoped: only the key's own organization's orders (none for a test key's sandbox tenant).

Request

curl "https://cetatraders.com/api/v1/orders" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "count": 1,
  "data": [
    {
      "buyer_ref": "PO-2026-118",
      "channel": "online",
      "currency": "EUR",
      "id": "9a7e1c44-3b2f-4d5e-8f60-7a1b2c3d4e5f",
      "payment_provider": "malaleem",
      "placed_at": "2026-11-12T09:41:07Z",
      "status": "paid",
      "subtotal_cents": 420000,
      "total_cents": 420000
    }
  ]
}

GET


        /api/v1/orders/{id}

scope read

One order, its lines and per-vendor payouts

Another organization's order answers 404, never 403 — saying forbidden would confirm it exists.

Parameter	In	Type	Description
id*	path	string (uuid)	The order id.

Request

curl "https://cetatraders.com/api/v1/orders/<id>" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "data": {
    "buyer_ref": "PO-2026-118",
    "channel": "online",
    "currency": "EUR",
    "id": "9a7e1c44-3b2f-4d5e-8f60-7a1b2c3d4e5f",
    "lines": [
      {
        "id": "1e2d3c4b-5a69-4788-9a0b-1c2d3e4f5a6b",
        "line_total_cents": 420000,
        "product_id": "6f1c2a9e-4b1d-4a43-9c55-1d2f4e8a7b10",
        "qty": 10,
        "title": "Arabica green coffee, 60 kg bag",
        "unit_price_cents": 42000,
        "vendor": {
          "id": "0b6f3c52-8c1e-4f7a-a2b9-3e5d7c9a1f22",
          "name": "Lisboa Roasters Lda"
        }
      }
    ],
    "payment_provider": "malaleem",
    "payouts": [
      {
        "commission_bps": 1000,
        "commission_cents": 42000,
        "currency": "EUR",
        "gross_cents": 420000,
        "net_cents": 378000,
        "vendor_id": "0b6f3c52-8c1e-4f7a-a2b9-3e5d7c9a1f22"
      }
    ],
    "placed_at": "2026-11-12T09:41:07Z",
    "status": "paid",
    "subtotal_cents": 420000,
    "total_cents": 420000
  }
}

404 not_found No such order for this organization.

Supplier intelligence

GET


        /api/v1/suppliers

scope read

Find suppliers

Explained ranking: every signal is reported, including those that scored zero. Records whose source licence forbids redistribution through an API are withheld and counted.

Parameter	In	Type	Description
product	query	string	Free text or a canonical key, e.g. `coffee`.
country	query	string	ISO 3166-1 alpha-2.
region	query	string	First-level division code.
city	query	string	City name.
role	query	string	e.g. `exporter`, `manufacturer`.
target_market	query	string	ISO country you sell into.
limit	query	integer	1–100, default 25.

Request

curl "https://cetatraders.com/api/v1/suppliers?product=…&country=…" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "attribution": [
    "INSEE Sirene (Licence Ouverte 2.0)"
  ],
  "count": 1,
  "data": [
    {
      "company": {
        "city": "Paris",
        "confidence": 90,
        "country": "FR",
        "id": "3c2b1a09-8f7e-4d6c-9b5a-0e1f2d3c4b5a",
        "legal_name": "Torréfaction du Port SAS",
        "region": "FR-IDF",
        "trade_name": "Café du Port",
        "website": "https://cafeduport.example"
      },
      "gaps": [],
      "score": 72,
      "signals": [
        {
          "explanation": "NAF 10.83Z maps to coffee",
          "key": "product_match",
          "score": 36,
          "weight": 40
        }
      ]
    }
  ],
  "gaps": [],
  "query": {
    "country_iso2": "FR",
    "product": "coffee"
  },
  "withheld": {
    "api": 0,
    "display": 0
  }
}

GET


        /api/v1/buyers

scope read

Find buyers (observed importers)

Companies a national register observed importing a commodity. No score: an observation is not a match. caveat carries the register's scope.

Parameter	In	Type	Description
product	query	string	Commodity.
country	query	string	Importing country, ISO alpha-2.
limit	query	integer	1–100, default 25.

Request

curl "https://cetatraders.com/api/v1/buyers?product=…&country=…" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "attribution": [
    "Canadian Importers Database (Open Government Licence – Canada)"
  ],
  "caveat": "The register lists major importers; absence is not evidence that a company does not import.",
  "count": 1,
  "data": [
    {
      "company": {
        "city": "Toronto",
        "confidence": 90,
        "country": "CA",
        "id": "3c2b1a09-8f7e-4d6c-9b5a-0e1f2d3c4b5a",
        "legal_name": "Torréfaction du Port SAS",
        "region": "CA-ON",
        "trade_name": "Café du Port",
        "website": "https://cafeduport.example"
      }
    }
  ],
  "gaps": [],
  "query": {
    "country_iso2": "CA",
    "product": "coffee"
  }
}

GET


        /api/v1/suppliers/{id}

scope read

One company

Everything held about a company: roles, products, identifiers, trade activity.

Parameter	In	Type	Description
id*	path	string (uuid)	Company id.

Request

curl "https://cetatraders.com/api/v1/suppliers/<id>" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "attribution": [
    "INSEE Sirene (Licence Ouverte 2.0)"
  ],
  "data": {
    "activity": [],
    "company": {
      "city": "Paris",
      "confidence": 90,
      "country": "FR",
      "id": "3c2b1a09-8f7e-4d6c-9b5a-0e1f2d3c4b5a",
      "legal_name": "Torréfaction du Port SAS",
      "region": "FR-IDF",
      "trade_name": "Café du Port",
      "website": "https://cafeduport.example"
    },
    "identifiers": [
      {
        "scheme": "siren",
        "value": "552100554"
      }
    ],
    "products": [
      {
        "canonical_key": "coffee",
        "hs_code": "090111",
        "self_declared": false
      }
    ],
    "roles": [
      {
        "confidence": 90,
        "role": "manufacturer",
        "self_declared": false
      }
    ]
  }
}

404 not_found No such company.
403 not_licensed_for_api The record's source does not permit redistribution through an API.

GET


        /api/v1/trade/market

scope read

Market size for a lane

A country-level statistic — never evidence about any company.

Parameter	In	Type	Description
product*	query	string	Commodity.
country*	query	string	Exporting country.
target_market	query	string	Importing country.

Request

curl "https://cetatraders.com/api/v1/trade/market?product=…&country=…" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "attribution": [
    "UN Comtrade"
  ],
  "caveat": "Country-level trade statistics, not company data.",
  "data": {
    "concept": "export_value",
    "observations": 5,
    "value_usd": "1250000000",
    "years": [
      2021,
      2022,
      2023,
      2024,
      2025
    ]
  }
}

422 could not resolve the product or country Unknown product or country.

Reference

GET


        /api/v1/reference/resolve

scope read

Resolve a product to its classification

Free text → canonical product → HS codes, with how it was matched and how sure.

Parameter	In	Type	Description
q*	query	string	e.g. `green coffee beans`.

Request

curl "https://cetatraders.com/api/v1/reference/resolve?q=…" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "data": {
    "canonical_key": "coffee",
    "confidence": 95,
    "hs_codes": [
      "090111"
    ],
    "match": "synonym",
    "name": "Coffee",
    "query": "green coffee beans"
  }
}

400 q is required No q.

GET


        /api/v1/sources

scope read

Data sources and what each permits

The source registry: status, tier and the permissions (store, display, redistribute, expose_api, train_ai).

Request

curl "https://cetatraders.com/api/v1/sources" \
  -H "Authorization: Bearer $CETA_KEY"

Response 200

{
  "count": 1,
  "coverage": [],
  "data": [
    {
      "key": "fr_sirene",
      "name": "INSEE Sirene",
      "organization": "INSEE",
      "permits": {
        "display": true,
        "expose_api": true,
        "redistribute": true,
        "store": true,
        "train_ai": false
      },
      "status": "verified",
      "tier": 1
    }
  ]
}

Agents (MCP)

POST


        /mcp

scope mcp

Model Context Protocol server

JSON-RPC 2.0: initialize, ping, tools/list, tools/call. The same tenant scoping and permissions as the REST API; a tool error is a result with isError: true.

Request

curl -X POST https://cetatraders.com/mcp \
  -H "Authorization: Bearer $CETA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":1,"jsonrpc":"2.0","method":"tools/list"}'

Response 200

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "description": "Full-text search across published products. Prices are integer minor units (price_cents) with the currency alongside …",
        "inputSchema": {
          "required": [
            "query"
          ],
          "type": "object"
        },
        "name": "search_products",
        "title": "Search the marketplace catalogue"
      }
    ]
  }
}