---
name: arkapi
description: Discover, fund, and safely call ArkAPI's Bitcoin-native pay-per-call APIs for security, OSINT, AI, Bitcoin, and utility tasks. Use when an agent needs an ArkAPI tool, needs to create or monitor a funded ArkAPI session, or must handle ArkAPI billing, retries, bearer tokens, or Tor access correctly.
---

# ArkAPI

Use ArkAPI's public machine-readable discovery documents and session API. The live service uses real Bitcoin mainnet sats and charges a flat 5 sats for each successful paid call.

Service URLs:

- Clearnet: `https://arkapi.dev`
- Tor guide: `https://arkapi.dev/tor/`
- Tor v3 onion: `http://bf7hn23jgyo5umvbi2lzzkb62ts3glxd2pnfksecqmyi4yglgdevs2ad.onion`

Use one origin consistently during a workflow. Do not rewrite an onion URL to HTTPS; Tor v3 provides authenticated end-to-end encryption for its `http://` onion origin.

## Discover a tool

1. Fetch `GET /v1/catalog` for the current endpoint list, HTTP methods, descriptions, and prices.
2. Read `/openapi.json` for request and response schemas. Never invent fields from an endpoint description.
3. Use `/.well-known/arkapi.json`, `/llms.txt`, or `/llms-full.txt` for agent-oriented discovery and examples.
4. Prefer the least expansive endpoint that satisfies the task. Ask before spending sats if the user's authority to spend is unclear.

Current discovery URLs:

- `https://arkapi.dev/v1/catalog`
- `https://arkapi.dev/openapi.json`
- `https://arkapi.dev/.well-known/arkapi.json`
- `https://arkapi.dev/llms.txt`
- `https://arkapi.dev/llms-full.txt`

Treat the live catalog and OpenAPI document as authoritative if this skill and the service ever differ.

## Create and fund a session

1. Create a fresh session with `POST /v1/sessions` and an explicit positive `amount_sats`. The public funding page offers 500, 1000, and 1500-sat presets; choose the smallest amount that covers the task.
2. Save the returned `ak_...` bearer token privately. Never print it in shared output, commit it, place it in a URL, or send it to another origin.
3. Pay either the returned mainnet Lightning invoice or mainnet Ark address. These are real sats; unused session balances are not refundable.
4. Poll `GET /v1/balance` with the bearer token until `status` is `active` and `balance_sats` is positive. Use a bounded interval such as five seconds and stop on expiry or a user-defined deadline.
5. Reuse that token until its balance is insufficient or the session expires after inactivity.

Create a session:

```bash
curl -sS https://arkapi.dev/v1/sessions \
  -H 'Content-Type: application/json' \
  -d '{"amount_sats":500}'
```

Check its balance. Passing curl configuration through standard input keeps the raw token out of shell history and curl's process arguments:

```bash
curl -sS --config - https://arkapi.dev/v1/balance <<EOF
header = "Authorization: Bearer $ARKAPI_TOKEN"
EOF
```

## Call an API

1. Match the exact method and payload in OpenAPI.
2. Send `Authorization: Bearer $ARKAPI_TOKEN`.
3. For JSON requests, send `Content-Type: application/json`.
4. Treat a paid call as successful only when the HTTP response and body indicate success.
5. Record `cost_sats` and `balance_remaining` when returned. Every successful paid endpoint currently costs 5 sats.

Example DNS lookup:

```bash
curl -sS --config - https://arkapi.dev/api/dns-lookup \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example.com"}' <<EOF
header = "Authorization: Bearer $ARKAPI_TOKEN"
EOF
```

## Handle failures safely

- For HTTP 400, 405, or 415, correct the method, headers, or payload. Do not blindly retry an invalid request.
- For HTTP 401, restore the correct token securely or create a new session. Never reveal the rejected token while troubleshooting.
- For HTTP 402, check `/v1/balance`. Wait if funding is still settling; otherwise create and fund a new session.
- For HTTP 429, obey `Retry-After` when present and use bounded backoff. Do not evade service limits.
- Validation, authentication, and failed-work responses should not consume sats; server-side failures refund a reserved charge. Confirm with `/v1/balance` when billing is uncertain.
- After a timeout or lost response, do not automatically repeat operations that create artifacts or have side effects, such as paste or image generation. Check the balance and ask for direction when duplicate work would matter.
- For retry-safe lookups, retry only a small number of times with exponential backoff and jitter.
- Stop and report the HTTP status plus sanitized error fields after repeated failures. Never include the bearer token, invoice, or full funding address in logs or reports.

## Use Tor

Use a Tor-capable client and resolve the onion hostname through Tor:

```bash
curl --socks5-hostname 127.0.0.1:9050 \
  http://bf7hn23jgyo5umvbi2lzzkb62ts3glxd2pnfksecqmyi4yglgdevs2ad.onion/health
```

- The same API paths and bearer token work over the onion service.
- Keep a workflow on one origin. Paste, screenshot, and generated-image URLs preserve the origin used for the request.
- Do not send clearnet-generated or onion-generated bearer tokens to any host other than the verified ArkAPI origins above.
- Expect occasional Tor circuit delays. Use bounded timeouts and retries; do not treat one timeout as proof that the service is down.