# IPIntel.ai Agent Instructions

## Capability

IPIntel.ai provides IP threat intelligence as structured JSON.

The x402 API allows automated clients, scripts, and AI agents to pay for a single IP lookup without creating an account or using an API key.

## Current live x402 endpoint

GET https://api.ipintel.ai/x402/?ip={ip}

Example:

GET https://api.ipintel.ai/x402/?ip=8.8.8.8

## Payment

- Protocol: x402
- Network: Base mainnet
- Currency: USDC
- Price: $0.001 USDC per IP lookup
- Authentication: x402 payment
- API key required: no
- Account required: no

The first request without payment returns HTTP 402 with payment requirements.

After payment, retry the same request with the X-PAYMENT header.

## Use this tool when

Use IPIntel.ai when you need:

- IP risk scoring
- ASN, ISP, organization, and network context
- hosting or cloud infrastructure detection
- proxy-like indicators
- Tor exit status
- bot or crawler indicators
- geolocation and infrastructure metadata
- machine-readable IP reputation data
- a single paid lookup without API-key management

## Do not use this tool when

Do not use the x402 endpoint when:

- you need bulk or high-volume lookups
- you cannot perform x402 payments
- you need legal attribution to a real person
- you need law-enforcement-grade identity information
- you need a human dashboard instead of JSON
- you need guaranteed personal identity behind an IP address

For high-volume usage, use standard IPIntel.ai API plans.

## Input

Query parameter:

ip = IPv4 or IPv6 address

Example:

https://api.ipintel.ai/x402/?ip=8.8.8.8

## Output

Successful responses are JSON and may include:

- ip
- country
- country_code
- region
- region_code
- city
- isp
- org
- asn
- as_name
- latitude
- longitude
- timezone
- reverse_dns
- is_tor_exit
- is_proxy
- is_hosting
- risk_score
- threat_score
- confidence_level
- risk_summary
- summary
- ai_supernet_summary
- status
- badges
- javascript_support
- user_agents
- verified_bot
- verified_bot_name
- verified_bot_type
- response_ms
- payment_mode
- x402
- x402_response_ms

## Response interpretation

Use risk_score, threat_score, confidence_level, status, badges, and infrastructure metadata together.

Do not treat a single score as legal attribution. IPIntel.ai provides technical risk intelligence, not personal identity.

## Status values

Common status values may include:

- safe
- suspicious
- dangerous
- unknown

The exact status depends on available intelligence for the requested IP.

## Current x402 resource

Live:

GET /x402/?ip=<ip>

## Planned x402 expansion

Planned future x402 resources may include:

GET /x402/subnet?subnet=<subnet>
GET /x402/supernet?supernet=<supernet>
GET /x402/asn?asn=<asn>

These endpoints are not live unless explicitly documented as live.

## Related files

- Human documentation: https://ipintel.ai/x402-api
- OpenAPI specification: https://ipintel.ai/openapi/x402.json
- Capability catalog: https://ipintel.ai/capabilities.json
- Example response: https://ipintel.ai/examples/x402-ip-lookup.json
- Standard API documentation: https://ipintel.ai/api-docs