# NordBastion — Agent integration

> NordBastion is a KYC-free Nordic VPS and dedicated server host, crypto-billed.
> An AI agent can complete the full lifecycle — signup, top-up, ordering,
> server management — without human intervention.

This file lists the machine-actionable surfaces. The editorial map is at
https://nordbastion.com/llms.txt and the human landing for agents is at
https://nordbastion.com/agents/.

## Native protocols

- [REST API v1](https://nordbastion.com/v1): JSON over HTTPS. Bearer API keys
  (`nb_live_…`) or OAuth 2.1 access tokens (`nb_at_…`).
- [OpenAPI 3.1 spec](https://nordbastion.com/.well-known/openapi.json):
  Machine-readable for `openapi-generator`, Stainless, Speakeasy etc.
- [MCP server](https://nordbastion.com/mcp): Streamable HTTP transport (POST + GET-SSE).
  Discoverable via the MCP server-card.
- [MCP server-card](https://nordbastion.com/.well-known/mcp/server-card.json):
  Auto-install in Claude / Cursor / OpenClaw from this URL.
- [A2A agent card](https://nordbastion.com/.well-known/agent.json):
  Skills, auth, and capabilities for A2A-aware orchestrators.
- [OAuth metadata](https://nordbastion.com/.well-known/oauth-authorization-server):
  RFC 8414. Token endpoint, scopes, supported grants. RFC 7591 DCR enabled.

## Authentication

- **API keys** — mint with `POST https://nordbastion.com/v1/auth/api-keys` after first top-up.
  Scopes: `read`, `billing`, `servers`, `full`.
- **OAuth client_credentials** — for M2M agents. Self-enroll via
  `POST https://nordbastion.com/v1/oauth/register` (no user account required).
- **OAuth password grant** — for agents acting on behalf of a known user.
  TOTP-enabled accounts must use `POST https://nordbastion.com/v1/auth/login` + `/auth/login/totp`.
- **Web Bot Auth** — RFC 9421 HTTP message signatures (Ed25519). Verified
  agents from OpenAI / Anthropic / Google / Amazon / Perplexity / Cloudflare
  receive relaxed rate-limits and a `bot_auth` audit-log marker.

## Payment

- Classic flow: `POST https://nordbastion.com/v1/billing/topups` → returns a per-coin
  deposit address + QR + expiry. Settle on-chain, the hub pushes a status
  callback, balance is credited (subject to the kill-switch — see below).
- **x402** (HTTP 402): on `POST https://nordbastion.com/v1/servers` an agent without
  sufficient balance can send `X-Payment-Mode: x402` to receive a payment
  quote, settle from its own wallet, then retry with `X-Payment: …`.
  Accepted coins for x402: USDCETH,USDT,XMR,LTC.
- **Kill-switch transparency**: when `TOPUP_CREDIT_ENABLED=false` the
  hub still completes the payment for accounting, but the balance is NOT
  credited and the topup object is returned with `kill_switch_blocked=true`
  and `status="error"`. Refund instructions are linked from the response.

## Public listing

- `GET https://nordbastion.com/v1/agents/directory` — agents that opted into the public
  registry (manually verified).
- `POST https://nordbastion.com/v1/agents/directory` — submit your agent (queued for
  verification, 24-72h).

## Editorial

- [Doctrine](https://nordbastion.com/doctrine/): the principles we run on.
- [Acceptable use](https://nordbastion.com/acceptable-use/): one hard limit.
- [Transparency report](https://nordbastion.com/transparency/): government
  + LE requests.
- [Warrant canary](https://nordbastion.com/warrant-canary/) — also queryable
  at `GET https://nordbastion.com/v1/transparency/canary`.
- [Status page](https://nordbastion.com/status/) — also queryable at
  `GET https://nordbastion.com/v1/transparency/status`.

## Rate limits

- Per API key: 120 req/min, 3000 req/hour (sustained 50/min).
- Anonymous (no Authorization): 30 req/min.
- Web Bot Auth verified: 5× the above.
- Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.

## Errors

- JSON envelope: `{"error":"<code>","message":"<human>","details":{…},"request_id":"req_<hex>"}`.
- Stable machine codes: `unauthorized`, `insufficient_scope`, `rate_limited`,
  `payment_required`, `topup_required`, `coin_unsupported`, `amount_too_low`,
  `amount_too_high`, `insufficient_balance`, `ssh_key_not_found`,
  `server_not_found`, `webhook_not_found`, `topup_not_found`, ...