# KeepBal quickstart

[Start with $1 free credit](/sign-up)

One key and one prepaid wallet for the tools your agent calls.

1. Create an account, then create a key in API keys and save it.
2. Give your agent the prompt below, install the Skill for your client, or try the three HTTP examples.
3. See each call and its cost in Usage after the call is recorded.

## Agent prompt

Paste this into your agent's chat:

```text
set up https://keepbal.com/SKILL.md
```

[Create your account](https://keepbal.com/sign-up) · [API keys](https://keepbal.com/console/keys) · [Connect with MCP](https://keepbal.com/docs/mcp)

## Install the Skill for your client

For a project-local install, run the shell commands for your client from your project root. Each downloads the hosted Skill and saves it as keepbal/SKILL.md in that client's skill directory.

Claude Code:

```sh
mkdir -p .claude/skills/keepbal
curl -fsSL https://keepbal.com/SKILL.md -o .claude/skills/keepbal/SKILL.md
```

[Claude Code Skill documentation](https://code.claude.com/docs/en/skills)

Cursor:

```sh
mkdir -p .cursor/skills/keepbal
curl -fsSL https://keepbal.com/SKILL.md -o .cursor/skills/keepbal/SKILL.md
```

[Cursor Skill documentation](https://cursor.com/docs/skills)

Codex:

```sh
mkdir -p .agents/skills/keepbal
curl -fsSL https://keepbal.com/SKILL.md -o .agents/skills/keepbal/SKILL.md
```

[Codex Skill documentation](https://developers.openai.com/codex/skills)

Tool search: Live. Models: Live.

## Catalog tools

2543 tools and 7 models are live. Call a catalog tool with POST /apis/v1/<path> and its JSON body. Fixed tools show a price per successful call; variable tools show the provider price plus 35%.

[Browse live tools](https://keepbal.com/catalog.json?page=1) · [Live model prices](https://keepbal.com/pricing)

## 1. Find a tool

Set KEEPBAL_API_KEY to your key, then search for a tool. Searching is free.

```sh
curl https://keepbal.com/apis/v1/discover \
  -H "Authorization: Bearer $KEEPBAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"exa"}'
```

Example discovery result (excerpt). Carry publicId unchanged through inspect and run:

```json
{
  "data": [
    {
      "publicId": "exa/contents",
      "path": "exa/contents"
    }
  ]
}
```

## 2. Check its price

Use the publicId from discovery. Inspecting its inputs and pricing metadata is free. Fixed tools show the per-call price; variable tools are billed at provider price + 35%. Inspect does not calculate an input-specific quote.

```sh
curl https://keepbal.com/apis/v1/inspect \
  -H "Authorization: Bearer $KEEPBAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"publicId":"exa/contents"}'
```

## 3. Run it

Fill input.body, input.queryParams, and input.pathParams as required by the tool. This page-contents example uses body parameters; the other buckets are empty.

```sh
curl https://keepbal.com/apis/v1/run \
  -H "Authorization: Bearer $KEEPBAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"publicId":"exa/contents","input":{"body":{"urls":["https://example.com"],"text":true},"queryParams":{},"pathParams":{}},"max_cost_usd":"0.10"}'
```

Catalog tool spend caps: REST top-level max_cost_usd, MCP input.max_cost_usd, or the X-KeepBal-Max-Cost-USD header. Caps must cover the estimate and fit your available balance; they persist through async completion. Costs above the cap fail without charge. Some variable tools require a cap or quantity.

Fixed tools charge the published per-call price. Variable tools charge the provider's reported actual cost plus the disclosed markup (currently 35%). Missing actual cost on variable tools charges $0. Quotes are estimates, labelled estimated_price; completed price is the settlement debit. Failed, blocked, or timed-out runs cost $0.

## First public tool call

```sh
curl https://keepbal.com/apis/v1/exa/contents \
  -H "Authorization: Bearer $KEEPBAL_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"urls":["https://example.com"],"text":true}'
```

## First model call

Select a live chat model ID from Models and replace MODEL_ID. Signup grants $1 credit once; tools and models share this wallet.

```sh
curl https://keepbal.com/v1/chat/completions -H "Authorization: Bearer $KEEPBAL_API_KEY" -H "Content-Type: application/json" --data '{"model":"MODEL_ID","messages":[{"role":"user","content":"Hello"}]}'
```

[Choose a live model](/models)

## For agents

[SKILL.md](https://keepbal.com/SKILL.md) · [llms.txt](https://keepbal.com/llms.txt) · [OpenAPI](https://keepbal.com/openapi.yaml)

[Docs](/docs)

[Quickstart](/docs/quickstart) · [Authentication](/docs/authentication) · [Billing](/docs/billing) · [Tools](/docs/tools) · [Models](/docs/models) · [MCP](/docs/mcp) · [Errors](/docs/errors) · [Rate limits and budgets](/docs/rate-limits-and-budgets)

[Next: Authentication](/docs/authentication)