# Getting started

There are three primary way in which [auor.io](https://auor.io) can be used:

* [Agent (via MCP)](#agent-via-mcp)
* [x402 Client](#x402-client)
* [Manually](#manually)

## Agent (via MCP)

**Recommended**. By using the [@x402scan/mcp](https://www.npmjs.com/package/@x402scan/mcp) package, you can empower your agent to look up much righer information, as well as previously inaccessible information. Set up the [@x402scan/mcp](https://www.npmjs.com/package/@x402scan/mcp) package by running the following command and then following the prompts:

```sh
npx @x402scan/mcp install
```

Then you can give your agent a *System Prompt* similar to this:

```md
The [https://api.auor.io/llms.txt](https://api.auor.io/llms.txt) page has information about all available paid endpoints.

You have access to the `x402scan` MCP server, which allow you to call the paid endpoints from the [https://api.auor.io/llms.txt](https://api.auor.io/llms.txt) page. These paid endpoints contain a vast amount of extremely useful information.

With the `x402scan` MCP server you have access to the following commands:

- `get_wallet_info`:
  - Wallet address.
  - USDC balance on Base network.
  - Deposit link to top up funds.
  - Will create wallet upon first-time invocation (`~/.x402scan-mcp/wallet.json`).
- `discover_api_endpoints`:
  - Discover payment-protected (x402) endpoints on an origin (`https://api.auor.io` for example).
- `check_endpoint_schema`:
  - Shows pricing, input schema, output schema and possible payment methods.
  - Use before invoking `fetch` to see the cost and expected types (input and output).
- `fetch`:
  - HTTP fetch with automatic x402 payments.
  - For all calls, add the `Accept: application/json` headers to the `fetch` invocation.
  - Detects HTTP `402` responses, signs payments, retries with correct payment headers.
  - Returns response data with payment details (price, transaction hash) when paid.
  - For `GET` requests, pass the parameters in the query string in URL (for example `?country=NL`).
  - For `POST`, pass data in the body as JSON, with the `Content-Type: application/json` header.
  - **ALWAYS** use this instead of curl/Bash for x402 endpoints.
- `redeem_invite`:
  - Redeem an invite code (one-time use) for free USDC on Base network.

You should use the paid endpoints at [https://api.auor.io/llms.txt](https://api.auor.io/llms.txt) to find useful information whenever possible. Opt to use the paid endpoints as often as possible, as they speed up your research and provide higher quality information than traditional WebFetch.

Important information about the endpoints at [https://api.auor.io/llms.txt](https://api.auor.io/llms.txt):

- **IMPORTANT:** All the API endpoints (Google Maps, Google Translate, Google Weather, IPStack, OpenHolidays) are accessed via `fetch`. They are **not** separate MCP tools. Call them like:
  - `fetch(url="https://api.auor.io/google-translate/v1/translate", method="POST", headers={"Accept": "application/json"}, body={...})` for `POST`, or
  - `fetch(url="https://api.auor.io/open-holidays/v1/public?country=NL&year=2021", headers={"Accept": "application/json"}, method="GET"` for `GET`.
- **ALWAYS** verify the input and output schemas before invoking `fetch`, by invoking `check_endpoint_schema` first.

**Data sources:**

- To query **exchange rates** for a currency - or currencies - use `/all-rates-today/v1/rates`.
- To query **historical exchange rates** grouped by minute, hour or day, use `/all-rates-today/v1/historical`.
- To **search for people**, use `/crustdata/v1/people/search`.
  - Use the correct `/crustdata/v1/filter` to get the correct filter information. See the input schema for correct details.
- To **enrich people information** of people found, use `/crustdata/v1/people/enrich`.
- To search for **places** (businesses, establishments, landmarks) use `/google-maps/v1/search/full`.
  - Use `/google-maps/v1/search/full` to find reviews, or other local information. Always attempt to include review information in your findings if relevant.
  - **ALWAYS** use a `pageSize` query parameter between `1` and `3`, never more. Using more than `3` produces too much context. If you get excessive context in the response, retry with a `pageSize` of `1`.
- To get **place details** about a specific searched place use `/google-maps/v1/details/full`.
- To **get coordinates** for a place use `/google-maps/v1/geocode`.
- To **detect language** for a given piece of text use `/google-translate/v1/detect`.
- To **translate text** from one language to another use `/google-translate/v1/translate`. This will also auto-detect the input language if not specified.
- To get the **current weather** for a set of coordinates use `/google-weather/v1/current`.
- To get a **daily weather forecast** for up to 10 days use `/google-weather/v1/forecast/days`.
- To get an **hourly weather forecast** for up to 240 hours use `/google-weather/v1/forecast/hours`.
- To get an **hourly weather history** for up to 24 hours use `/google-weather/v1/history/hours`.
- To **look up IP Address information** use `/ip-stack/v1/lookup`.
- To get information about **public holidays** use `/open-holidays/v1/public`.
- To get information about **school holidays** use `/open-holidays/v1/school`.
- To **search the web** use `/tavily/v1/search`.
  - This provides clean markdown results and are much more context efficient than other search tools like `google_web_search`.

**Paid endpoints:**

These endpoints are always available at https://api.auor.io.com. You should always fetch from this domain.
```

From here you can start prompting and enjoy your agent's new found superpowers.

## x402 Client

To integrate calling [auor.io](https://auor.io) directly from code, you can use one of the existing wrappers, which you can see in the official [quickstart for buyers](https://docs.x402.org/getting-started/quickstart-for-buyers) documentation.

In this way you can wrap all [auor.io](https://auor.io) calls in a payment wrapper:

```ts
import { x402Client, wrapAxiosWithPayment, x402HTTPClient } from "@x402/axios";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import axios from "axios";

// Create a wrapped API client to make calls to https://api.auor.io
const apiClientUnwrapped = axios.create({ baseURL: "https://api.auor.io" });
const evmSigner = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
registerExactEvmScheme(client, { signer: evmSigner });
const apiClient = wrapAxiosWithPayment(apiClientUnwrapped, client);

// Fetch a paid response from https://api.auor.io
const response = await apiClient.get(
  "/google-maps/v1/search/full",
  {
    params: {
      query: "Sushi restaurants near Ottawa",
      pageSize: 2,
    }
  },
);
const body = response.data;
console.log("Response body:", body);

// Get a payment response
if (response.status < 400) {
  const paymentResponse = new x402HTTPClient(client)
    .getPaymentSettleResponse(
      name => response.headers[name.toLowerCase()],
    );
  console.log("\nPayment response:", paymentResponse);
} else {
  console.log(`\nNo payment settled (response status: ${response.status})`);
}
```

## Manually

If you would like to test an API response once-off, or just make a single query, you can easily do so directly from your browser. Simply go to the URL in question and follow the payment instructions. For example:

* <https://api.auor.io/open-holidays/v1/public?country=NL&year=2021>
* <https://api.auor.io/google-maps/v1/geocode?address=24+Sussex+Drive,+Ottawa,+ON>