# x402tools API Reference

x402tools provides paid API access to various data enrichment and search services using the x402 payment protocol.

## Authentication

All endpoints require x402 payment. Include payment headers as per the HTTP 402 specification. Payments are processed on Base mainnet (eip155:8453).

## Base URL

All endpoints are relative to the API server base URL.

---

# Google Maps API

## POST /api/google-maps/text-search/full
Search for places using a text query with full field details.
Price: $0.09 per request

Request Body:
- textQuery (string, required): Search query text
- maxResultCount (number, 1-20, default: 20): Maximum results to return
- excludeFields (string[], optional): Fields to exclude from response
- pageToken (string, optional): Pagination token
- locationBias (object, optional): Bias results to a location
  - circle.center.latitude (number)
  - circle.center.longitude (number)
  - circle.radius (number, 0-50000 meters)
- includedType (string, optional): Filter by place type
- languageCode (string, default: "en"): Language for results
- openNow (boolean, optional): Filter to currently open places
- minRating (number, 0-5, optional): Minimum rating filter
- priceLevels (string[], optional): Price level filter (PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE, PRICE_LEVEL_VERY_EXPENSIVE)

Example:
```json
{
  "textQuery": "coffee shops in San Francisco",
  "maxResultCount": 5
}
```

Response: Array of places with id, displayName, formattedAddress, location, types, photos, rating, reviews, opening hours, contact info, and service options.

---

## POST /api/google-maps/text-search/partial
Search for places using a text query with partial field details (lower cost).
Price: $0.08 per request

Request/Response: Same as /text-search/full but returns fewer fields.

---

## POST /api/google-maps/nearby-search/full
Search for places near a geographic location with full details.
Price: $0.09 per request

Request Body:
- locationRestriction (object, required): Search area
  - circle.center.latitude (number)
  - circle.center.longitude (number)
  - circle.radius (number, 0-50000 meters)
- maxResultCount (number, 1-20, default: 20): Maximum results
- excludeFields (string[], optional): Fields to exclude
- includedTypes (string[], max 50, optional): Place types to include
- excludedTypes (string[], max 50, optional): Place types to exclude
- languageCode (string, default: "en"): Language for results
- rankPreference (string, default: "POPULARITY"): "POPULARITY" or "DISTANCE"

Example:
```json
{
  "locationRestriction": {
    "circle": {
      "center": { "latitude": 37.7749, "longitude": -122.4194 },
      "radius": 1000
    }
  },
  "maxResultCount": 5
}
```

---

## POST /api/google-maps/nearby-search/partial
Search for places near a geographic location with partial details.
Price: $0.08 per request

Request/Response: Same as /nearby-search/full but returns fewer fields.

---

## GET /api/google-maps/place-details/full
Get full details for a specific place by ID.
Price: $0.06 per request

Query Parameters:
- placeId (string, required): Google Place ID
- excludeFields (string, optional): Comma-separated fields to exclude
- languageCode (string, default: "en"): Language for results

Example: GET /api/google-maps/place-details/full?placeId=ChIJN1t_tDeuEmsRUsoyG83frY4

---

## GET /api/google-maps/place-details/partial
Get partial details for a specific place by ID.
Price: $0.05 per request

Query Parameters: Same as /place-details/full

---

# Apollo API

## POST /api/apollo/people-search
Search for people/contacts matching criteria.
Price: $0.02 per request

Request Body:
- q_keywords (string, optional): Keywords to search across all fields
- person_titles (string[], optional): Job titles to match
- person_not_titles (string[], optional): Job titles to exclude
- person_seniorities (string[], optional): Seniority levels (owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern)
- person_locations (string[], optional): City, state, or country
- q_organization_domains (string[], optional): Company domains
- organization_locations (string[], optional): Organization locations
- organization_ids (string[], optional): Apollo organization IDs
- organization_num_employees_ranges (string[], optional): Ranges like "1,10", "11,50", "51,200", "201,500", "501,1000", "1001,5000", "5001,10000", "10001,"
- organization_industry_tag_ids (string[], optional): Industry filters
- excludeFields (string[], optional): Fields to exclude
- page (number, min: 1, default: 1): Page number
- per_page (number, 1-100, default: 25): Results per page

Example:
```json
{
  "q_keywords": "software engineer",
  "person_locations": ["San Francisco"],
  "per_page": 5
}
```

Response:
- people: Array of person objects with id, name, email, title, linkedin_url, organization, employment_history, etc.
- pagination: { page, per_page, total_entries, total_pages }

---

## POST /api/apollo/org-search
Search for organizations/companies matching criteria.
Price: $0.03 per request

Request Body:
- q_keywords (string, optional): Keywords to search
- organization_locations (string[], optional): Locations
- organization_num_employees_ranges (string[], optional): Employee count ranges
- organization_industry_tag_ids (string[], optional): Industry filters
- organization_ids (string[], optional): Apollo organization IDs
- q_organization_domains (string[], optional): Company domains
- excludeFields (string[], optional): Fields to exclude
- page (number, min: 1, default: 1): Page number
- per_page (number, 1-100, default: 25): Results per page

Example:
```json
{
  "q_keywords": "saas",
  "organization_locations": ["United States"],
  "per_page": 5
}
```

Response:
- organizations: Array with id, name, domain, website_url, linkedin_url, industry, estimated_num_employees, annual_revenue, funding info, location, etc.
- pagination: { page, per_page, total_entries, total_pages }

---

## POST /api/apollo/people-enrich
Enrich a person's profile with additional data.
Price: $0.08 per request

Request Body:
- first_name (string, optional): Person's first name
- last_name (string, optional): Person's last name
- name (string, optional): Full name if first/last not available
- email (string, optional): Email address (best matching signal)
- domain (string, optional): Company domain
- organization_name (string, optional): Company name
- linkedin_url (string, optional): LinkedIn profile URL
- excludeFields (string[], optional): Fields to exclude

Example:
```json
{
  "email": "tim@apple.com"
}
```

Response:
- person: Person object or null
- status: Match status string

---

## POST /api/apollo/people-enrich/bulk
Enrich multiple people in a single request.
Price: $0.45 per request

Request Body:
- details (array, 1-10 items, required): Array of person lookup objects
  - first_name, last_name, name, email, domain, organization_name, linkedin_url (all optional)
- excludeFields (string[], optional)

Example:
```json
{
  "details": [
    { "email": "tim@apple.com" },
    { "email": "satya@microsoft.com" }
  ]
}
```

Response:
- matches: Array of { person, status } objects

---

## POST /api/apollo/org-enrich
Enrich an organization's profile by domain.
Price: $0.06 per request

Request Body:
- domain (string, required): Company domain, e.g., "apollo.io"
- excludeFields (string[], optional): Fields to exclude

Example:
```json
{
  "domain": "apollo.io"
}
```

Response:
- organization: Organization object or null
- status: Match status string

---

## POST /api/apollo/org-enrich/bulk
Enrich multiple organizations in a single request.
Price: $0.38 per request

Request Body:
- domains (string[], 1-10 items, required): Array of company domains
- excludeFields (string[], optional): Fields to exclude

Example:
```json
{
  "domains": ["apollo.io", "stripe.com"]
}
```

Response:
- matches: Array of { organization, status } objects

---

# Grok API (X/Twitter Data)

## POST /api/grok/x-search
Search X (Twitter) posts using natural language.
Price: $0.02 per request

Request Body:
- query (string, required): Natural language search query
- maxResults (number, 1-20, default: 10): Maximum posts to return
- includeMedia (boolean, default: true): Include media attachments
- dateRange (object, optional): Filter by date
  - from (string, optional): ISO date string
  - to (string, optional): ISO date string

Example:
```json
{
  "query": "AI agents",
  "maxResults": 5
}
```

Response:
- posts: Array of post objects with id, text, author (handle, displayName, verified, followerCount), createdAt, metrics (likes, reposts, replies, views), media, urls
- summary (string, optional): AI-generated summary of results
- searchContext: { query, resultCount, dateRange }

---

## POST /api/grok/user-search
Search for X (Twitter) users.
Price: $0.02 per request

Request Body:
- query (string, required): Search query for users (name, handle, bio keywords, or role)
- maxResults (number, 1-20, default: 10): Maximum users to return

Example:
```json
{
  "query": "AI researcher",
  "maxResults": 5
}
```

Response:
- users: Array of user objects with handle, displayName, bio, followerCount, followingCount, verified, location, website, joinedDate, profileImageUrl
- searchContext: { query, resultCount }

---

## POST /api/grok/user-posts
Get recent posts from a specific X user.
Price: $0.02 per request

Request Body:
- handle (string, required): X username without the @
- maxResults (number, 1-20, default: 10): Maximum posts to return

Example:
```json
{
  "handle": "elonmusk",
  "maxResults": 5
}
```

Response:
- handle: User's handle
- displayName: User's display name
- posts: Array of post objects with id, text, createdAt, likes, reposts, replies, views, isReply, urls
- postCount: Number of posts returned

---

# Exa API (Web Search & Research)

## POST /api/exa/search
Semantic web search for finding relevant pages.
Price: $0.02 per request

Request Body:
- query (string, required): Search query
- numResults (number, 1-100, default: 10): Number of results
- type (string, optional): Search type (neural, fast, auto, deep; default: auto)
- category (string, optional): Filter by category (company, research paper, news, pdf, github, tweet, personal site, linkedin profile, financial report)
- includeDomains (string[], optional): Only include these domains
- excludeDomains (string[], optional): Exclude these domains
- startCrawlDate (string, optional): Filter by crawl date
- endCrawlDate (string, optional): Filter by crawl date
- startPublishedDate (string, optional): Filter by publish date
- endPublishedDate (string, optional): Filter by publish date
- includeText (string[], optional): Must contain these terms
- excludeText (string[], optional): Must not contain these terms
- userLocation (string, optional): User location for personalization
- additionalQueries (string[], optional): Additional query variations
- contents (object, optional): Content extraction options
  - text (boolean | object): Extract text content
  - highlights (object): Extract highlighted sentences
  - summary (object): Generate summary

Example:
```json
{
  "query": "best practices for building AI agents",
  "numResults": 5
}
```

Response:
- results: Array with title, url, publishedDate, author, score, text, highlights, summary
- searchType: Resolved search type used
- requestId: Request identifier

---

## POST /api/exa/find-similar
Find pages similar to a given URL.
Price: $0.02 per request

Request Body:
- url (string, required): URL to find similar pages for
- numResults (number, 1-100, default: 10): Number of results
- includeDomains, excludeDomains, date filters, contents (same as /search)

Example:
```json
{
  "url": "https://openai.com",
  "numResults": 5
}
```

Response:
- results: Array of similar pages with title, url, score, text, etc.
- requestId: Request identifier

---

## POST /api/exa/contents
Extract content from specific URLs.
Price: $0.02 per request

Request Body:
- urls (string[], required): URLs to extract content from
- text (boolean | object, optional): Extract text content
  - maxCharacters (number): Limit text length
  - includeHtmlTags (boolean): Include HTML tags
- highlights (object, optional): Extract highlights
  - numSentences (number): Sentences per highlight
  - highlightsPerUrl (number): Highlights per URL
  - query (string): Focus highlights on query
- summary (object, optional): Generate summaries
  - query (string): Focus summary on query
- livecrawl (string, optional): "never", "fallback", "always", "preferred"
- livecrawlTimeout (number, optional): Timeout in ms
- subpages (number, optional): Number of subpages to crawl
- subpageTarget (string | string[], optional): Target subpage patterns
- extras (object, optional): Additional extraction
  - links (number): Extract links
  - imageLinks (number): Extract image links

Example:
```json
{
  "urls": ["https://example.com"]
}
```

Response:
- results: Array with url, title, text, highlights, summary
- statuses: Array of crawl statuses per URL
- requestId: Request identifier

---

## POST /api/exa/answer
Get an AI-generated answer to a question based on web search.
Price: $0.02 per request

Request Body:
- query (string, required): Question or query to answer
- stream (boolean, default: false): Stream response
- text (boolean, default: false): Include source text

Example:
```json
{
  "query": "What is the capital of France?"
}
```

Response:
- answer: AI-generated answer string
- citations: Array of source citations with id, url, title, author, publishedDate, text

---

# Firecrawl API (Web Scraping)

## POST /api/firecrawl/scrape
Scrape and extract content from a URL.
Price: $0.02 per request

Request Body:
- url (string, required): URL to scrape

Example:
```json
{
  "url": "https://example.com"
}
```

Response:
- url: Final URL after redirects
- title: Page title
- content: Page content as markdown (truncated to 8000 chars)

---

## POST /api/firecrawl/search
Search the web and get scraped results.
Price: $0.02 per request

Request Body:
- query (string, required): Search query
- limit (number, 1-10, default: 5): Maximum results

Example:
```json
{
  "query": "best coffee shops",
  "limit": 5
}
```

Response:
- results: Array with title, url, description, snippet
- query: Original query
- resultCount: Number of results returned

---

# Clado API (LinkedIn & Contact Enrichment)

## POST /api/clado/contacts-enrich
Enrich contact information from LinkedIn URL, email, or phone number.
Price: $0.03 per request

Request Body (exactly one identifier required):
- linkedin_url (string, optional): LinkedIn profile URL to enrich
- email (string, optional): Email address to enrich
- phone (string, optional): Phone number to enrich
- email_enrichment (boolean, default: false): Request email enrichment (costs credits when found)
- phone_enrichment (boolean, default: false): Request phone enrichment (costs credits when found)

Example:
```json
{
  "linkedin_url": "https://www.linkedin.com/in/satyanadella"
}
```

Response:
- data: Array of contact info objects
  - error (boolean, optional): Whether an error occurred
  - contacts: Array of contact objects
    - type: "email" or "phone"
    - value: Contact value
    - rating: Confidence score (0-100)
    - subType (optional): Contact subtype
  - social: Array of social profile objects
    - link: Social profile URL
    - type: Social network type
    - rating: Confidence score (0-100)

---

## POST /api/clado/linkedin-scrape
Scrape full LinkedIn profile data including experience, education, skills, and posts.
Price: $0.05 per request

Request Body:
- linkedin_url (string, required): LinkedIn profile URL to scrape

Example:
```json
{
  "linkedin_url": "https://www.linkedin.com/in/satyanadella"
}
```

Response:
- profile: Profile object
  - id, name, headline, summary, location, title
  - linkedin_profile_url, profile_picture_url
  - num_of_connections, twitter_handle
  - websites, emails, criteria
- experience: Array of experience objects
  - employee_title, employer_name, employee_description
  - employer_linkedin_id, employer_logo_url
  - start_date, end_date, location, is_current
- education: Array of education objects
  - institute_name, degree_name, field_of_study
  - institute_linkedin_id, institute_logo_url
  - start_date, end_date, description
- skills: Array of skill strings
- languages: Array of language strings
- location: Geographic location
- certifications: Array of certification objects
- honors: Array of honor objects
- posts: Array of post objects
  - post_url, title, action, order_in_profile

---

# Common Features

## Field Filtering
Most endpoints support an `excludeFields` parameter to reduce response size by omitting specific fields.

## Pagination
Apollo search endpoints support pagination via `page` and `per_page` parameters. Google Maps search endpoints support pagination via `pageToken`.

## Error Handling
All endpoints return standard HTTP status codes. Payment-required responses (402) include x402 payment instructions in headers.