x402-places

x402-places

POI concierge over OpenStreetMap Overpass with optional Yelp enrichment — restaurants, cafes, anything, per query. $0.002 in USDC on Base or Solana per call, and the places come back in the response body: opening hours, phone, website, address, cuisine, and the full OSM tag set.

Docs site: https://nirholas.github.io/x402-places/

Why x402 for this

Places data is either free-but-raw (you run your own Overpass client and parse OSM tags) or polished-but-gated (a commercial API with a key, a contract, and a monthly floor). Neither fits an agent that needs one clean answer about one neighbourhood, once. x402 makes the middle ground possible: the route quotes $0.002 in the 402 response, the agent pays on whichever chain it holds funds on, and it gets normalised POI records with no account, no key, and no minimum.

Quickstart

git clone https://github.com/nirholas/x402-places
cd x402-places
npm install
npm run dev            # http://localhost:4022 — no configuration needed

See the price with no wallet at all:

curl -s "http://localhost:4022/search?lat=41.3851&lon=2.1734&radius=300&category=cafe&limit=2" | jq
# 402 + accepts: [ USDC on Base, USDC on Solana ]

Then buy it, from an agent (wallet funded with Base Sepolia USDC — https://faucet.circle.com):

PRIVATE_KEY=0xYourTestKey npm run client

API

Full reference: docs/api.md · openapi.json

How x402 works

Pay in USDC on Base or Solana — your client picks the rail.

1. 402 — the route, called without payment, replies HTTP 402 with an accepts array holding both rails: exact price ($0.002 → 2000 USDC base units), asset, and payTo.
2. Sign — on Base, the client signs an EIP-3009 USDC authorization (no gas from the payer). On Solana, it signs an SPL transferChecked whose fee payer is the facilitator's sponsor account (so the buyer needs USDC only, no SOL).
3. Settle — the server hands the payload to the facilitator (https://x402.org/facilitator), which verifies and settles on the chosen chain.
4. 200 — the same request returns the artifact in the body, with the settlement receipt in the X-PAYMENT-RESPONSE header.

Those are the suite's public receive addresses and the server's defaults. Set PAY_TO_ADDRESS / SOLANA_PAY_TO_ADDRESS to be paid yourself.

Walkthroughs: examples/curl.md · examples/agent-client.ts · docs/tutorial.md

Real backend / API keys

All variables: .env.example

For AI agents

• skill.md — agent-facing skill file: endpoints, prices, schemas, both payment rails. Point your agent at it.
• GET /.well-known/x402 — discovery manifest listing every resource with both networks. Indexable by x402scan.com, the x402 Bazaar, and agentic.market.
• MCP — examples/mcp-tool.md exposes these routes as Claude MCP tools, with per-wallet spend caps and a claude_desktop_config.json example.
• More: docs/agents.md

Docs

• Landing: https://nirholas.github.io/x402-places/
• Tutorial · API reference · For AI agents

Support

Questions, bugs, or a listing request: nichxbt@gmail.com · open an issue

License

Apache-2.0. Part of the x402 Suite.

Star History

Support the project

If x402-places saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/x402-places and it has the context it needs.

More from the same author

• All repositories by nirholas: the full catalog, grouped by topic
• three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
• Questions or ideas: open an issue or start a discussion

Contributors