Read references/api.md for request and response formats.
Read references/query-patterns.md when the user's search intent is vague.
Read references/error-handling.md when an API call fails or returns no data.

Protocol Contract

For runtime execution, follow this protocol exactly.

Use only these runtime endpoints:

GET {UNIPROFIT_API_BASE_URL}/openclaw/credential/me
POST {UNIPROFIT_API_BASE_URL}/openclaw/search/query

Execution checklist:

send authentication with X-UniProfit-Key
send search requests as POST
send search requests with a JSON body
keep source, filters, page, and page_size in the request body

Do not replace this skill with generic supplier-search or buyer-search endpoints.

Canonical runtime pattern:

validate the credential if needed with GET /openclaw/credential/me
build a query plan
execute search with POST /openclaw/search/query
summarize the current result window

Run scripts/check_credential.py if the credential may be missing or invalid.

Use This Skill When

the user wants overseas buyer or importer leads
the user wants exhibition lead records
the user wants procurement or sourcing requirement records
the user wants structured trade search against UniProfit-owned datasets

Do not use this skill for:

sending emails
generating email drafts
general web research outside UniProfit data

Planning Rules

Prefer structured filters over broad searches.

Use a two-step workflow:

build an internal query plan
execute the query only if the plan is reliable enough

Do not turn every natural-language request directly into an API call.

Choose one source first:

importers for importers or buyers
exhibition for exhibition leads
requirements for procurement demand

Use only supported filters for the chosen source:

importers: company_name, country_code, hs_code, hs_codes, date_period, is_verified
exhibition: fair_name, state, company_name, procurement_category, contact_person
requirements: country, purchase_title, purchasing_unit, keyword, min_amount, max_amount, currency

Important:

importers does not support keyword
product keyword search should usually use requirements
if the user wants buyer search by product on importers, prefer HS code first

Language strategy:

first query with the user's original wording
if the first query returns no result, allow one language-aware fallback that better matches the likely storage language of the chosen source
do not immediately translate everything into English by default
do not chain many multilingual retries

Do not send unsupported filters. The backend rejects them with 400.

If the user does not specify a source, choose the best fit and state it briefly.

Before calling the API, decide these four items internally:

recommended source
recommended filters
confidence level
whether one critical field is still missing

If confidence is low, ask the user one short clarifying question instead of querying immediately.

If confidence is medium or high, query once with the best structured plan.

For product-style requests:

product keyword + buyer intent: prefer requirements first unless the user already has HS code
product keyword + explicit HS code: use importers
company lookup: use importers
fair or exhibitor lookup: use exhibition

Execution Flow

Read the user request and infer buyer search, exhibition search, or demand search intent.
Build a query plan:
- source
- filters
- confidence
- missing critical field, if any
If one critical field is missing and the plan is weak, ask one short question.
Otherwise run scripts/search_trade.py, or make the same protocol call to POST /openclaw/search/query with X-UniProfit-Key and a JSON body.
If the first query returns no result, allow one fallback retry using the same source with a closer language match for that source.
Summarize the search source, filters, current window size, whether more results may exist, and the best leads.
If there are still no results, suggest one narrower or broader retry based on the same plan.

Planning Heuristics

Prefer these planning rules:

If the user says buyer / importer / customer and gives company-like terms, choose importers.
If the user gives a fair name, exhibitor context, or exhibition lead request, choose exhibition.
If the user gives product words without HS code, especially for demand discovery, choose requirements.
If the user asks for buyers by product but only gives a plain product phrase, do not send keyword to importers.
If the user asks for buyers by product and also gives HS code, use importers with hs_code or hs_codes.
If the user gives only country + generic product phrase and no HS code, prefer one short clarifying question over a blind importers query.
For requirements, keep the user's original country and product wording on the first attempt when the database is likely to store those fields in the same language.
Use at most one language fallback after a zero-result first attempt. Example: keep 哈萨克斯坦 + 家居用品 first, then try one closer storage-language fallback such as household if needed.

Output Style

Start with:

source searched
filters applied
current window result count
whether more results may exist

Then present the most actionable rows. Prioritize company name, geography, contact clues, and product relevance.

For requirements results, prefer showing:

purchase_title
purchasing_unit
email when present
country
deadline
amount and currency when present

Describe results as a current query window rather than a complete database count. If the runtime response includes has_more, explain that more matching results may exist and guide the user to narrow the filters for a more focused next step.

Preferred wording pattern:

This query returned {returned_count} results from {source}.
if has_more = true: More matching results may be available beyond the current window. Narrow the filters to continue with a more focused search.
if query_hint exists: restate it as the next best search refinement suggestion

Do not dump raw JSON unless the user asks for it.

uniprofit-trade-search

UniProfit Trade Search

Quick Start