# Vortex

> Vortex tells a buying agent whether a store can actually deliver to its destination, and what the order really costs once it lands there.

## Why this exists

- Product search is solved. Delivery is not. Every catalogue will happily return items the buyer can never receive.
- Most storefronts serve one country. Measured on real stores: Allbirds and Gymshark publish shipping to exactly one destination, while Kith publishes 197.
- The shelf price is the smallest part of a cross-border order. A US$120 item into Brazil lands near US$220 once import tax and state tax are applied.
- Ask Vortex before you commit, and report what happened after. Reporting is free, and a claim the merchant's own feed contradicts is stored but never counted.

## Using it, with no human in the loop

1. `POST /v1/identity` with your wallet address and an EIP-191 signature. Free, no account, no human. You get a handle and a bearer token.
2. `GET /v1/find?need=<what you want>&destination=<ISO country>` — one result per store, and only stores that can deliver there.
3. `GET /v1/feasibility?store=<domain>&destination=<ISO country>` when you already have a store in mind.
4. `GET /v1/landed?destination=<ISO country>&item_usd=<price>` before you commit, because the shelf price is not the total.
5. `POST /v1/report` afterwards. Free, re-checked against the merchant's own feed, so a false claim about a competitor never counts.

## Where the answers come from

- Shipping reach, currency and accepted cards, read from the `/meta.json` every storefront publishes about itself.
- Live price and stock, from the public product feed, parsed into integer micro-USD so no rounding creeps into a comparison.
- Price and stock history, appended on change since the day the collector started. This is what makes `history` able to say whether a price is good.
- Import rules per destination, versioned with an effective date. Every landed cost names the rule it used.
- Freight, from buying agents that reported what they were quoted. Vortex does not create carts on merchant sites to scrape rates.

Nothing here is self-reported to Vortex by a merchant, and no ranking position is for sale.

## Prices

| Operation | Price (USD) | What it does |
| --- | --- | --- |
| `capabilities` | free | Return the full machine-readable manifest of Vortex: every operation, its price in USD, its input schema and how to pay. Free. |
| `identity.create` | free | Turn a wallet address into a permanent Vortex identity and an API token. Free, and grants a small trial credit. No signup, no email, no human. |
| `whoami` | free | Your handle, wallet, balance and usage. Free. |
| `credit.deposit` | free | Buy Vortex credit with USDC on Base over x402. One on-chain settlement, then every call is debited off-chain. |
| `find` | 0.005000 | Search real storefronts for a product and get back only the ones that can ship to your destination, with live price and stock. Every other product index answers what matches the words; this one answers what matches the words and can be delivered. |
| `feasibility` | 0.002000 | Everything Vortex knows about whether one storefront can serve one destination: its published shipping zones, the currency it charges in, the cards it takes, what buyers reported, and whether its reach changed recently. Returns a verdict, not just data. |
| `landed` | 0.003000 | Item plus shipping plus import tax plus local tax, itemised, for a destination — and the name and effective date of the tax rule applied. A US$120 item into Brazil lands near US$220; the shelf price is not the number to budget against. |
| `history` | 0.002000 | The recorded price and stock series for a product, where today sits against its own record, how often it has gone out of stock, and every change to where its store ships. |
| `watch` | 0.005000 | Register standing interest in a product or a store: a price drop below your threshold, a return to stock, or a store that stops shipping to your destination. |
| `report` | free | Tell Vortex how a purchase actually went. Free, and checked against the merchant's own feed before it counts — a claim the store contradicts is stored and marked contradicted rather than believed. |

## Paying

Payment is x402 (USDC on eip155:8453). Deposit once, spend per call.
Per-call on-chain settlement would cost more than most calls are worth, so Vortex keeps a prepaid balance and debits it off-chain.

## Endpoints

- Manifest: https://vortex.rohnelt.dev/v1/capabilities
- OpenAPI: https://vortex.rohnelt.dev/openapi.json
- MCP (streamable HTTP): https://vortex.rohnelt.dev/mcp
- x402 discovery: https://vortex.rohnelt.dev/.well-known/x402