Official client • v0.1.5

From discovery to paid API call in one command.

The ArkAPI client discovers the live catalog, validates inputs from OpenAPI, calls tools with Bearer or Ark-402 authentication, and turns the current API into MCP tools for compatible agents.

Dynamic MCP toolsReadable Chat resultsBearer + Ark-402Local spend budgetsNo token in command history

Linux AMD64 Linux ARM64 Release manifest

Install

Download the binary and signed checksum set for your architecture, verify them, then install it on your path.

base=https://arkapi.dev/downloads/v0.1.5 curl -fSLO "$base/arkapi-v0.1.5-linux-amd64" curl -fSLO "$base/SHA256SUMS" curl -fSLO "$base/SHA256SUMS.sig" curl -fSLO "$base/signing-key.pub.pem" openssl pkeyutl -verify -pubin -inkey signing-key.pub.pem \ -rawin -in SHA256SUMS -sigfile SHA256SUMS.sig sha256sum --ignore-missing -c SHA256SUMS sudo install -m 0755 arkapi-v0.1.5-linux-amd64 /usr/local/bin/arkapi arkapi version

ARM64 users should substitute arkapi-v0.1.5-linux-arm64. Public-key DER SHA-256: 894ad62142c0b5077ddf255f81b236afd925c6c01e0f921f732f391059f67d82.

Bearer quick start

Create a session and save its token directly into a private client file. The token is omitted from normal output.

arkapi session create --amount 500 # Pay the returned Ark address or Lightning invoice arkapi balance arkapi catalog arkapi call btc-price --query currency=USD

Token files are created with mode 0600. The client never accepts a token as a command-line flag.

Give an agent MCP tools

arkapi mcp serve reads the live catalog and OpenAPI document, then publishes each paid endpoint as a typed MCP tool. Add this stdio server to any compatible host:

{ "mcpServers": { "arkapi": { "command": "/usr/local/bin/arkapi", "args": ["mcp", "serve"], "env": { "ARKAPI_AUTH": "bearer", "ARKAPI_TOKEN_FILE": "/private/path/to/arkapi/token" } } } }

OpenAI-compatible Chat is exposed as arkapi_chat_completions. Client v0.1.4 returns the assistant answer as normal MCP text, preserves the complete OpenAI response in structuredContent, and includes billing receipt metadata for Bearer or Ark-402 calls.

Client v0.1.5 reconciles the local usage counter with the final receipt, so an included Ark-402 call reported at 0 sats no longer remains counted as a 5-sat spend.

MCP Chat returns one completed, non-streaming result. Keep discovery at https://arkapi.dev, not the Chat hostname; use https://chat.arkapi.dev/v1/chat/completions directly when live SSE streaming is required. A misconfigured Chat discovery base now returns an actionable correction.

The default local policy allows at most 25 sats per call and 100 sats of API calls per UTC day. Change those only when the agent's authority requires it.

Ark-402 mode

Ark-402 lets a dedicated Bark wallet pay once, then sign each request against its credit. Install the matching helper alongside the client.

Helper AMD64 Helper ARM64

export ARKAPI_AUTH=ark402 export ARK402_CLIENT_BARKD_URL=http://127.0.0.1:3000 export ARK402_CLIENT_BARKD_DATADIR=/private/path/to/.bark arkapi call btc-price --query currency=USD

Automatic top-ups are off by default. Use a dedicated, low-balance wallet and keep wallet credentials outside prompt context.

Tor with proxy-side DNS

export HTTP_PROXY=socks5h://127.0.0.1:9050 export HTTPS_PROXY=socks5h://127.0.0.1:9050 export ARK402_PROXY=socks5h://127.0.0.1:9050 export NO_PROXY=127.0.0.1,localhost

HTTP_PROXY covers the HTTP onion origin, HTTPS_PROXY covers HTTPS origins, and ARK402_PROXY covers the Ark-402 helper's merchant requests. The helper keeps its local Bark REST connection outside the explicit proxy.

Opt-in automatic top-ups

Only enable payment automation when the agent is authorized to spend. Both per-top-up and daily limits are enforced locally.

export ARKAPI_ARK402_AUTO_PAY=1 export ARKAPI_ARK402_MAX_TOPUP_SATS=100 export ARKAPI_ARK402_DAILY_TOPUP_BUDGET_SATS=500

A request with an uncertain network outcome remains charged against the local budget until reconciled. This prevents a timeout from silently widening spending authority.

Built-in guardrails

Control	Default
Maximum API cost per call	25 sats
Daily API-call budget	100 sats
Ark-402 automatic payment	Off
Maximum Ark-402 top-up	100 sats
Daily Ark-402 top-up budget	500 sats
Bearer token transport	HTTPS, localhost, Tor onion, or I2P only

Inspect current local usage with arkapi usage. See the agent skill for billing, retry, Tor, I2P, and ambiguous-response guidance.

Verifiable releases

Every release uses permanent versioned URLs and includes an Ed25519-signed checksum file, CycloneDX SBOMs, minimal source archives, and machine-readable build provenance. See the verification guide, checksums, signature, and provenance.