{"openapi":"3.1.0","info":{"title":"Vortex API","version":"0.1.0","description":"Vortex tells a buying agent whether a store can actually deliver to its destination, and what the order really costs once it lands there.\n\nProduct search is solved. Delivery is not. Every catalogue will happily return items the buyer can never receive.\nMost storefronts serve one country. Measured on real stores: Allbirds and Gymshark publish shipping to exactly one destination, while Kith publishes 197.\nThe 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.\nAsk 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."},"servers":[{"url":"https://vortex.rohnelt.dev"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Token from identity.create."}}},"paths":{"/v1/capabilities":{"get":{"operationId":"capabilities","summary":"Describe Vortex","description":"Return the full machine-readable manifest of Vortex: every operation, its price in USD, its input schema and how to pay. Free.\n\nWhen to use: Call this first if you have never used Vortex and want to know what it can do and what it costs.\n\nPrice: US$0.000000 per call, debited from your prepaid balance.","tags":["discovery"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"service":"Vortex","operations":["find","feasibility","landed"]}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[]}},"/v1/identity":{"post":{"operationId":"identity_create","summary":"Claim an identity","description":"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.\n\nWhen to use: Call this once, before anything else. You need the returned token for every other call.\n\nPrice: US$0.000000 per call, debited from your prepaid balance.","tags":["identity"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"handle":"swift-heron-4f2a","token":"vtx_sk_...","balance_usd":"0.020000"}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"wallet":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Your EVM wallet address. This is your permanent identity."},"signature":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"EIP-191 personal_sign of the message field, proving you control the wallet."},"message":{"type":"string","minLength":8,"maxLength":200,"description":"Must contain your wallet address and a timestamp within the last 10 minutes."},"label":{"description":"A name for your own reference.","type":"string","maxLength":64}},"required":["wallet","signature","message"]}}}}}},"/v1/whoami":{"get":{"operationId":"whoami","summary":"Who am I","description":"Your handle, wallet, balance and usage. Free.\n\nWhen to use: Call this to check your balance before a run, or to confirm your token still works.\n\nPrice: US$0.000000 per call, debited from your prepaid balance.","tags":["identity"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"handle":"swift-heron-4f2a","balance_usd":"0.870000","trial":false}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[]}},"/v1/credit/deposit":{"post":{"operationId":"credit_deposit","summary":"Top up balance","description":"Buy Vortex credit with USDC on Base over x402. One on-chain settlement, then every call is debited off-chain.\n\nWhen to use: Call when your balance is low. Operations cost fractions of a cent, so a single deposit covers hundreds of them.\n\nPrice: US$0.000000 per call, debited from your prepaid balance.","tags":["billing"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"credited_usd":"1.000000","balance_usd":"1.020000","tx":"0x..."}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"amount_usd":{"description":"One of 1, 5 or 20. Defaults to 1.","anyOf":[{"type":"string","maxLength":24},{"type":"number"}]}}}}}}}},"/v1/find":{"get":{"operationId":"find","summary":"Find something that can actually reach you","description":"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.\n\nWhen to use: Call this before shopping anywhere else. Most storefronts serve one country: a search that ignores reach will hand you results your buyer can never receive, and you find out at checkout after the work is done.\n\nPrice: US$0.005000 per call, debited from your prepaid balance.","tags":["commerce","shipping"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"need":"merino wool sneakers","destination":"BR","considered":1842,"reachable_stores":61,"results":[{"product":"https://kith.com/products/example","title":"Wool Runner","store":"kith.com","price_usd":"140.000000","available":true,"reach":"listed"}]}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[{"name":"need","in":"query","required":true,"description":"What you are looking for, in plain language. Example: merino wool sneakers.","schema":{"type":"string","minLength":3,"maxLength":200,"description":"What you are looking for, in plain language. Example: merino wool sneakers."}},{"name":"destination","in":"query","required":true,"description":"ISO 3166-1 alpha-2 country the goods must reach. Example: BR, US, DE.","schema":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country the goods must reach. Example: BR, US, DE."}},{"name":"limit","in":"query","required":false,"description":"How many stores to return.","schema":{"default":5,"description":"How many stores to return.","type":"integer","minimum":1,"maximum":20}},{"name":"max_price_usd","in":"query","required":false,"description":"Skip anything above this shelf price.","schema":{"description":"Skip anything above this shelf price.","anyOf":[{"type":"string","maxLength":24},{"type":"number"}]}},{"name":"in_stock_only","in":"query","required":false,"description":"Only return products with a variant in stock.","schema":{"default":true,"description":"Only return products with a variant in stock.","type":"boolean"}}]}},"/v1/feasibility":{"get":{"operationId":"feasibility","summary":"Can this store deliver here","description":"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.\n\nWhen to use: Call this when you already have a store in mind and are about to spend real money. Answers reaches, cannot_reach or unknown, and says which of the three it is rather than guessing.\n\nPrice: US$0.002000 per call, debited from your prepaid balance.","tags":["commerce","shipping"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"store":"allbirds.com","destination":"BR","verdict":"cannot_reach","reasons":["The store ships to 1 destination, and BR is not among them."],"payment":{"currency":"USD","card_brands":["visa","master"]}}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[{"name":"store","in":"query","required":true,"description":"Store domain or any URL on it. Example: allbirds.com","schema":{"type":"string","maxLength":300,"description":"Store domain or any URL on it. Example: allbirds.com"}},{"name":"destination","in":"query","required":true,"description":"ISO 3166-1 alpha-2 country the goods must reach. Example: BR, US, DE.","schema":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country the goods must reach. Example: BR, US, DE."}}]}},"/v1/landed":{"get":{"operationId":"landed","summary":"What it really costs there","description":"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.\n\nWhen to use: Call this before committing to a cross-border purchase, and before comparing two stores in different countries. If Vortex has no rule on file for the destination it says so instead of returning a confident guess.\n\nPrice: US$0.003000 per call, debited from your prepaid balance.","tags":["commerce","tax"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"destination":"BR","lines":[{"label":"item","usd":"120.000000"},{"label":"import tax","usd":"52.000000","basis":"60% of customs value, less US$20.00"},{"label":"local tax","usd":"29.240000","basis":"17% of customs value plus import tax"}],"total_usd":"201.240000","rule":{"name":"Programa Remessa Conforme","effective_from":"2024-08-01"}}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[{"name":"destination","in":"query","required":true,"description":"ISO 3166-1 alpha-2 country the goods must reach. Example: BR, US, DE.","schema":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country the goods must reach. Example: BR, US, DE."}},{"name":"product","in":"query","required":false,"description":"A product URL. Its price is looked up for you.","schema":{"description":"A product URL. Its price is looked up for you.","type":"string","maxLength":2048,"format":"uri"}},{"name":"item_usd","in":"query","required":false,"description":"Shelf price, if you are not passing a product URL.","schema":{"description":"Shelf price, if you are not passing a product URL.","anyOf":[{"type":"string","maxLength":24},{"type":"number"}]}},{"name":"shipping_usd","in":"query","required":false,"description":"Freight, if you already have a quote. Omitted means the total excludes it and says so.","schema":{"description":"Freight, if you already have a quote. Omitted means the total excludes it and says so.","anyOf":[{"type":"string","maxLength":24},{"type":"number"}]}}]}},"/v1/history":{"get":{"operationId":"history","summary":"Is this price good","description":"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.\n\nWhen to use: Call this when you have a candidate and want to know whether to buy now or wait. Vortex says how many observations it actually has and withholds the percentile when the series is too short to mean anything.\n\nPrice: US$0.002000 per call, debited from your prepaid balance.","tags":["commerce","price"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"product":"https://kith.com/products/example","observations":34,"price":{"current_usd":"140.000000","low_usd":"112.000000","percentile":20},"stock":{"in_stock_now":true,"went_out":2,"came_back":2}}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"parameters":[{"name":"product","in":"query","required":true,"description":"A product URL exactly as Vortex returned it from find.","schema":{"type":"string","maxLength":2048,"format":"uri","description":"A product URL exactly as Vortex returned it from find."}},{"name":"days","in":"query","required":false,"description":"How far back to look.","schema":{"default":90,"description":"How far back to look.","type":"integer","minimum":1,"maximum":365}}]}},"/v1/watch":{"post":{"operationId":"watch","summary":"Tell me when it changes","description":"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.\n\nWhen to use: Call this instead of polling find on a schedule. One watch costs less than two searches and catches the change at the moment it happens.\n\nPrice: US$0.005000 per call, debited from your prepaid balance.","tags":["commerce"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"watching":"https://kith.com/products/example","watch_id":"wch_01H..."}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"kind":{"type":"string","enum":["price_drop","back_in_stock","reach_change"],"description":"What you want to be told about."},"product":{"description":"Required for price_drop and back_in_stock.","type":"string","maxLength":2048,"format":"uri"},"store":{"description":"Required for reach_change.","type":"string","maxLength":300},"destination":{"description":"Required for reach_change.","type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$"},"below_usd":{"description":"For price_drop: notify under this price.","anyOf":[{"type":"string","maxLength":24},{"type":"number"}]},"callback_url":{"description":"Optional. Vortex POSTs here on a change.","type":"string","format":"uri"}},"required":["kind"]}}}}}},"/v1/report":{"post":{"operationId":"report","summary":"Report what happened","description":"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.\n\nWhen to use: Call this after any purchase attempt, good or bad. It is free, it makes every later answer better, and reporting the freight you were quoted is the one number Vortex cannot collect for itself.\n\nPrice: US$0.000000 per call, debited from your prepaid balance.","tags":["commerce","trust"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"recorded":true,"verified":true,"note":"The merchant's own data agrees with this report. It counts."}}}},"402":{"description":"Balance too low. The body carries the exact deposit call to make."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"product":{"type":"string","maxLength":2048,"format":"uri","description":"A product URL exactly as Vortex returned it from find."},"outcome":{"type":"string","enum":["delivered","blocked_at_checkout","price_wrong","out_of_stock","never_arrived"],"description":"What actually happened when you tried to buy."},"destination":{"description":"Where you were shipping to.","type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Za-z]{2}$"},"shipping_usd":{"description":"What freight was quoted. This is what makes landed costs accurate for everyone.","anyOf":[{"type":"string","maxLength":24},{"type":"number"}]},"detail":{"description":"What happened, in your own words.","type":"string","maxLength":500}},"required":["product","outcome"]}}}}}}}}