---
name: orthogonal
version: 1.2.0
description: >-
  Discover and call verified APIs for web search, scraping, enrichment, data
  retrieval, and other external capabilities through one catalog and one
  balance. Use when a task needs fresh or structured data that the user's
  existing tools do not provide.
homepage: https://orthogonal.com
---

# Orthogonal

Orthogonal gives agents one interface to discover, call, and pay for a catalog of verified APIs. The same catalog is available through the CLI, MCP server, TypeScript SDK, and REST API.

## When to use Orthogonal

Use Orthogonal when a task needs an external capability such as live web search, scraping, contact or company enrichment, financial data, social data, or another structured API.

Before building a custom scraper, using a generic fetch for structured data, or saying data is inaccessible, search the catalog. If the user already has a dedicated tool, API key, or MCP server for the exact service, use that first; Orthogonal fills gaps rather than replacing their existing setup.

## Agent workflow

1. **Discover** — Search with a short description of the capability you need.
2. **Inspect** — Read the endpoint schema, required parameters, and price. Never guess parameter names.
3. **Quote when needed** — For dynamic pricing or a potentially large call, estimate the cost before execution.
4. **Run** — Put inputs in the locations shown by the schema: path, query, or JSON body.
5. **Verify** — Check the returned result and price. Save binary or large output to a file.

For work spanning several sources, split it into focused calls and combine the results. Start with conservative result limits, especially when pricing may scale with volume.

## CLI

Install and authenticate:

```bash
npm install -g @orth/cli
orth login
orth whoami
```

Get an API key from https://orthogonal.com/dashboard/settings/api-keys. For non-interactive environments, set `ORTHOGONAL_API_KEY` instead of running `orth login`.

To create a new agent account without a password, follow https://orthogonal.com/agent-signup.md. Verify both email and phone ownership; successful signup returns an API key. Eligible accounts receive a one-time $1 starter credit grant. Check `starterCredit.amountUsd`: an ineligible account still receives its key with a $0 grant and a reason. The offer is limited to one account per phone across human and agent signup. Never create more accounts to bypass this limit.

The core workflow:

```bash
# Discover matching endpoints
orth search "company enrichment from domain"

# Inspect one endpoint's schema and price
orth api show <api-slug> <path>

# Estimate cost without executing
orth run <api-slug> <path> --dry-run -b '{"key":"value"}'

# Execute with query parameters
orth run <api-slug> <path> -q key=value -q limit=5

# Execute with a JSON body and save the response
orth run <api-slug> <path> -X POST -b '{"key":"value"}' -o result.json
```

Useful commands:

| Command | Purpose |
|---|---|
| `orth search "<need>"` | Find relevant APIs with natural language |
| `orth api list` | Browse all APIs |
| `orth api show <slug> [path]` | Inspect endpoints or one endpoint's parameters |
| `orth run <slug> <path>` | Execute an endpoint |
| `orth code <slug> <path>` | Generate TypeScript integration code |
| `orth balance` | Check available credits |
| `orth usage` | Review recent calls and spend |

Run `orth <command> --help` for the current flags and syntax.

## MCP

Connect any MCP-compatible client to:

```json
{
  "mcpServers": {
    "orthogonal": {
      "url": "https://mcp.orthogonal.com"
    }
  }
}
```

The MCP server exposes `search`, `get_details`, `quote`, `use`, and `integrate`, plus batch variants for details and execution. Follow the same discover → inspect → quote → run workflow.

## SDK

```bash
npm install @orth/sdk
```

```typescript
import Orthogonal from "@orth/sdk";

const orth = new Orthogonal({
  apiKey: process.env.ORTHOGONAL_API_KEY,
});

const result = await orth.run({
  api: "apollo",
  path: "/v1/people/search",
  query: { title: "CTO", limit: 5 },
});

console.log(result.data, result.price);
```

## REST API

Base URL: `https://api.orthogonal.com`

Authenticate with `Authorization: Bearer $ORTHOGONAL_API_KEY`.

| Method | Endpoint | Purpose |
|---|---|---|
| `POST` | `/v1/search` | Discover APIs using natural language |
| `POST` | `/v1/details` | Get an endpoint's full schema and price |
| `GET` | `/v1/list-endpoints` | Browse the complete catalog |
| `POST` | `/v1/run` | Execute an API call |
| `POST` | `/v1/integrate` | Generate integration code |

For machine-readable discovery without authentication:

- `https://api.orthogonal.com/discover` returns the catalog as JSON, including endpoint schemas, pricing, and payment URLs.
- `https://api.orthogonal.com/openapi.json` returns the catalog as an OpenAPI 3.1 document.

Example:

```bash
curl -X POST 'https://api.orthogonal.com/v1/run' \
  -H "Authorization: Bearer $ORTHOGONAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"api":"olostep","path":"/v1/scrapes","body":{"url_to_scrape":"https://example.com"}}'
```

## Pricing and payments

Calls are metered individually with no subscription or per-provider account. Search and details show endpoint pricing, and run responses include the charged price. Use prepaid credits by default. Payable Base endpoints automatically accept USDC or OUSD over x402, and MPP endpoints automatically accept USDC.e or OUSD on Tempo. Choose the currency from the endpoint's HTTP 402 payment offers; no provider configuration change is needed.

OUSD is Open USD issued by Bridge. On Base, use a Permit2-capable x402 v2 client: install `@x402/fetch` or `@x402/axios` together with `@x402/evm`, all v2.17 or later. Import `ExactEvmScheme` from `@x402/evm/exact/client` and register it with your signing account on the `x402Client` for `eip155:8453` before wrapping fetch or axios. Approve an OUSD allowance for Permit2 before paying. The initial approval requires ETH for Base gas and is not sponsored. On Tempo, select the OUSD currency in the MPP challenge. Circle Gateway nanopayments (np) and on-chain credit funding continue to use USDC.

Do not blindly repeat a paid call after an ambiguous timeout or interrupted response. Check usage first, then retry only when the earlier call is known not to have completed.

### Check balance and email a Stripe top-up link

Use the API key returned by signup. Check balance and available packages:

```bash
curl --fail-with-body --silent --show-error 'https://api.orthogonal.com/v1/credits/balance' \
  -H "Authorization: Bearer $ORTHOGONAL_API_KEY"
curl --fail-with-body --silent --show-error 'https://api.orthogonal.com/v1/credits/pricing'
```

Read the current package price, including its processing fee, and ask the user before requesting a payment email. With their approval, request a link (this example adds $25 of credits and currently costs $26.25 including the 5% fee):

```bash
curl --fail-with-body --silent --show-error \
  -X POST 'https://api.orthogonal.com/v1/credits/email-payment-link' \
  -H "Authorization: Bearer $ORTHOGONAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"credits":25}'
```

The endpoint sends the Stripe checkout link only to the account's current verified primary email. Do not supply an email, account ID, organization ID, or redirect URL. It requires a personal API key; organization top-ups use the dashboard.

Check `emailSent`, `email`, `totalLabel`, and `checkoutUrl` in the response. If `emailSent` is false, give the user the existing checkout link instead of repeatedly requesting more emails. Requests are limited to one per minute and five per account per day; honor HTTP 429 and do not retry in a loop.

Creating a link does not charge a card or add credits. The user completes Stripe checkout; never enter payment details or complete payment on their behalf without explicit authorization. After they confirm payment, check `GET /v1/credits/balance` again. Payment processing can take a moment; avoid rapid polling. Keep API keys and checkout URLs out of shared logs.

## Links

- API catalog: https://orthogonal.com/discover
- Documentation: https://docs.orthogonal.com
- Dashboard: https://orthogonal.com/dashboard