cpbox-local-pois

USE FOR getting local business/POI details. Requires POI IDs obtained from web-search (with result_filter=locations). Returns full business information inclu...

Security Scan

The skill is an instruction-only wrapper for a paid external API to fetch local POI details; its requirements and instructions are consistent with that purpose but involve external payment and network operations you should review before use.

Purpose & Capability

Name/description (local POI details) match the SKILL.md: it documents a GET to cpbox.io to return business details and requires POI IDs from a prior web-search. No unrelated credentials or binaries are requested.

Instruction Scope

Instructions are limited to calling the cpbox API and following the x402 payment flow. They explicitly reference obtaining POI IDs from a separate web-search skill and optionally sending user location via X-Loc-Lat/Long headers. The instructions do instruct network calls to external domains (cpbox.io and cppay.finance) and to sign payment requests; they do not ask the agent to read local files or unrelated env vars.

Install Mechanism

The skill is instruction-only (no install spec) which minimizes on-disk changes. However, the docs recommend using npx @springmint/x402-payment or x402-sdk-go to automate payment — npx will dynamically fetch code from npm at runtime, which is a potential supply-chain/runtime risk if you don't trust the package or registry.

Credentials

The manifest requests no environment variables or credentials. That said, the x402 payment flow will require you to sign payment requests using a wallet/key on your machine; the SKILL.md claims keys 'stay on your machine' (no storage here). This is proportionate to a paid API but you must ensure private keys/wallets are handled locally and not exfiltrated.

Persistence & Privilege

always is false, the skill is user-invocable and instruction-only with no code or install that would persist or modify other skills or agent config. It does not request elevated persistence or system-wide config changes.

Assessment

This skill is an instructions-only connector for a paid CPBOX local-POI API and appears internally consistent. Before installing or using it, verify you trust the external domains (https://www.cpbox.io and https://www.cppay.finance) and the referenced payment SDK (@springmint/x402-payment) because the flow requires signing a payment. Be aware that sending X-Loc-Lat/X-Loc-Long will transmit user location to the provider, and using npx will download and run code from npm at runtime. Do not expose private keys; use a wallet that keeps keys local and inspect the payment SDK/docs and the GitHub prerequisites link before proceeding.

Local POIs (Search API)

Paid Local POIs proxy via x402 pay-per-use (HTTP 402).

Prerequisites: This skill requires x402-payment. Complete the setup steps before first use.

Two-step flow: This endpoint requires POI IDs from a prior web search.

1. Call web-search with result_filter=locations to get POI IDs from locations.results[].id
2. Pass those IDs to this endpoint to get full business details

Security: Documentation only — no executable code or credentials. Wallet/keys stay on your machine; never stored here.

Service URLs

Role	Domain
API Provider	https://www.cpbox.io
Facilitator	https://www.cppay.finance

Endpoint (Agent Interface)

GET /api/x402/local-pois

Payment Flow (x402 Protocol)

1. First request -> 402 Payment Required with requirements JSON
2. Sign & retry with PAYMENT-SIGNATURE -> result JSON

With @springmint/x402-payment or x402-sdk-go, payment is automatic.

Quick Start (cURL)

Get POI Details

curl -s "https://www.cpbox.io/api/x402/local-pois" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -G \
  --data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA="

Multiple POIs with Location Headers

curl -s "https://www.cpbox.io/api/x402/local-pois" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Loc-Lat: 37.7749" \
  -H "X-Loc-Long: -122.4194" \
  -G \
  --data-urlencode "ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=" \
  --data-urlencode "ids=loc4HTAVTJKP4RBEBZCEMBI3NG26YD4II4PATIHPDYI=" \
  --data-urlencode "units=imperial"

Note: POI IDs are opaque strings returned in web search locations.results[].id. IDs are ephemeral and expire after ~8 hours. The example IDs above are for illustration — fetch fresh IDs via web-search with result_filter=locations. Use --data-urlencode since IDs may contain =.

POI ID Cache & Invalidation

Aspect	Policy
TTL	POI IDs are valid for approximately 8 hours from issuance.
Invalidation	IDs cannot be refreshed or extended. After expiry, use web-search with result_filter=locations to obtain new IDs.
Caching	You may cache POI details (hours, ratings, etc.) locally for display; do not cache IDs beyond 8 hours for reuse in local-pois or local-descriptions.
Expired ID	Requests with expired IDs return empty or error results. Re-run the web search to get fresh IDs.

Using with x402-payment

npx @springmint/x402-payment \
  --url "https://www.cpbox.io/api/x402/local-pois?ids=loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA%3D" \
  --method GET

Parameters

Parameter	Type	Required	Default	Description
ids	string[]	Yes	—	POI IDs from web search results (1-20)
search_lang	string	No	en	Language preference (2+ char language code)
ui_lang	string	No	en-US	UI language (locale code, e.g., "en-US")
units	string	No	null	metric (km) or imperial (miles)

Location Headers (Optional)

For distance calculation from user location:

Header	Type	Range	Description
X-Loc-Lat	float	-90.0 to 90.0	User latitude
X-Loc-Long	float	-180.0 to 180.0	User longitude

Response Fields

The response has type: "local_pois" and a results array of LocationResult objects:

Field	Type	Description
title	string	Business/POI name
url	string	Canonical URL for the location
provider_url	string	Provider page URL
type	string	Always "location_result"
id	string	POI identifier (opaque string, valid ~8 hours)
description	string?	Short description
postal_address.type	string	Always "PostalAddress"
postal_address.displayAddress	string	Formatted display address
postal_address.streetAddress	string?	Street address
postal_address.addressLocality	string?	City
postal_address.addressRegion	string?	State/region
postal_address.postalCode	string?	Postal/ZIP code
postal_address.country	string?	Country code
contact.telephone	string?	Phone number
contact.email	string?	Email address
rating.ratingValue	float?	Average rating (≥0)
rating.bestRating	float?	Max possible rating
rating.reviewCount	int?	Number of reviews
rating.profile.name	string?	Rating provider name
rating.profile.url	string?	Rating provider URL
opening_hours.current_day	object[]?	Today's hours (abbr_name, full_name, opens, closes)
opening_hours.days	object[][]?	Hours for each day of the week (same structure)
coordinates	[float, float]?	[latitude, longitude] tuple
distance.value	float?	Distance from user location
distance.units	string?	Distance unit (km or miles)
categories	string[]	Business categories (default [])
price_range	string?	Price indicator ($, $$, $$$, $$$$)
serves_cuisine	string[]?	Cuisine types (restaurants)
thumbnail.src	string?	Thumbnail image URL
thumbnail.original	string?	Original image URL
profiles	object[]?	External profiles (name, url, long_name, img)
reviews.reviews_in_foreign_language	bool	Whether reviews in a foreign language are available
pictures.results	object[]?	Photo thumbnails
action	object?	Action to take — has type (string) and url (string)
results	object[]?	Related web results (LocationWebResult with meta_url)
timezone	string?	IANA timezone (e.g., America/Los_Angeles)
timezone_offset	int?	UTC timezone offset

Example Response

{
  "type": "local_pois",
  "results": [
    {
      "type": "location_result",
      "title": "Park Mediterranean Grill",
      "url": "https://yelp.com/biz/park-mediterranean-grill-sf",
      "provider_url": "https://yelp.com/biz/park-mediterranean-grill-sf",
      "id": "loc4CQWMJWLD4VBEBZ62XQLJTGK6YCJEEJDNAAAAAAA=",
      "postal_address": {
        "type": "PostalAddress",
        "displayAddress": "123 Main St, San Francisco, CA 94102",
        "streetAddress": "123 Main St",
        "addressLocality": "San Francisco",
        "addressRegion": "CA",
        "postalCode": "94102",
        "country": "US"
      },
      "contact": { "telephone": "[phone]" },
      "thumbnail": {
        "src": "https://example.com/thumb.jpg",
        "original": "https://example.com/original.jpg"
      },
      "rating": {
        "ratingValue": 4.5,
        "bestRating": 5.0,
        "reviewCount": 234,
      },
      "opening_hours": {
        "current_day": [
          { "abbr_name": "Mon", "full_name": "Monday", "opens": "07:00", "closes": "21:00" }
        ]
      },
      "coordinates": [37.7749, -122.4194],
      "distance": { "value": 0.3, "units": "miles" },
      "categories": ["Mediterranean", "Greek"],
      "price_range": "$$",
      "serves_cuisine": ["Mediterranean", "Greek"],
      "timezone": "America/Los_Angeles"
    }
  ]
}

Getting POI IDs

POI IDs come from the Web Search API (web-search) with result_filter=locations:

# 1. Search for local businesses
curl -s "https://www.cpbox.io/api/x402/web-search?q=coffee+shops+near+me&result_filter=locations" \
  -H "Accept: application/json" \
  -H "X-Loc-Lat: 37.7749" \
  -H "X-Loc-Long: -122.4194"

# 2. Extract POI IDs from locations.results[].id
# 3. Use those IDs with this endpoint

Use Cases

• Local business lookup: Retrieve full details (hours, contact, address) for POIs surfaced in web search
• Restaurant discovery pipeline: Search for restaurants, fetch POI details, filter by cuisine/rating/price_range
• Business hours checker: Get opening_hours for a business to determine if currently open
• Location-aware application: Combine with location headers to get distance calculations for nearby POIs

Notes

• ID format: Opaque strings (use --data-urlencode for cURL)
• Units: metric or imperial for distance measurement preference
• Max IDs: Up to 20 IDs per request