# CrossCompute Agent Skill

This document is optimized for autonomous agents (including OpenClaw).

Goal: if a Base wallet already has funds, agent should complete onboarding + top-up + inference with no extra research.

Default output language policy:

- Use English by default.
- Only switch language when user explicitly requests that language.

## Trust & Safety Contract (For Agent Runtimes)

This skill is designed to be auditable and consent-driven:

1. Default mode is non-spending (`CROSSCOMPUTE_ALLOW_SPEND=false`).
2. Spending mode must be explicitly enabled by owner (`CROSSCOMPUTE_ALLOW_SPEND=true`).
3. Wallet creation can be disabled (`CROSSCOMPUTE_ALLOW_WALLET_CREATE=false`).
4. Every paid top-up exposes on-chain `txHash`.
5. Payment challenge fields must be used as-is (no mutation).
6. Only `POST /api/agents/topup` is charging; register/usage/inference are not x402 charge points.
7. Trust policy is machine-readable at `/.well-known/agent-trust-policy.json`.

If your runtime requires proof of intent, use these env flags as explicit owner consent.

If an owner gives you this URL, you should:

1. Register yourself on CrossCompute.
2. Reuse an existing local Base wallet (or create one if missing).
3. Self-top-up credits with x402 (USDC on Base).
4. Call CrossCompute OpenAI-compatible `/v1` endpoints.
5. Monitor credits and auto-topup when low.

Base URL:

`https://www.crosscompute.io`

## 1) 30-Second Trust Verification (Recommended Before Any Spend)

```bash
curl -sS https://www.crosscompute.io/health
curl -sS https://www.crosscompute.io/.well-known/agent-trust-policy.json
curl -sS https://www.crosscompute.io/openapi.json
```

Verify these conditions:

- `health.paymentChannels.x402.enabled=true` before expecting live top-ups.
- Trust policy default is non-spending.
- OpenAPI contains `/api/agents/topup` (charging) and `/v1/chat/completions` (inference).

## 2) No-Research Fast Path (Recommended)

Use this exact flow.

1. Install runtime deps once.
2. Run the official quickstart script.
3. Persist wallet + API key files.
4. Re-run same script whenever credits are low.

Install and run:

```bash
mkdir -p crosscompute-agent && cd crosscompute-agent
npm init -y
npm i viem @x402/core @x402/evm
curl -sS https://www.crosscompute.io/examples/crosscompute-agent-quickstart.mjs -o run.mjs

# Safe default (read-only / no spend):
AGENT_ID=openclaw-prod-001 \
AGENT_NAME="OpenClaw Production Agent" \
node run.mjs

# Spending mode (explicit owner consent):
BASE_WALLET_PRIVATE_KEY=0xYOUR_KEY \
AGENT_ID=openclaw-prod-001 \
AGENT_NAME="OpenClaw Production Agent" \
CROSSCOMPUTE_ALLOW_SPEND=true \
node run.mjs
```

Optional language override:

```bash
CROSSCOMPUTE_SYSTEM_PROMPT="Always respond in English." node run.mjs
```

What this script already does:

- `GET /health`
- `GET /.well-known/agent-trust-policy.json`
- `POST /api/agents/register`
- `GET /api/agents/usage`
- `POST /api/agents/topup` with x402 challenge signing
- `GET /v1/models` for runtime model discovery
- `POST /v1/chat/completions`
- `GET /api/agents/usage` again

What it does not do unless authorized:

- It does not execute x402 payment when `CROSSCOMPUTE_ALLOW_SPEND=false`.
- It does not create a wallet if `CROSSCOMPUTE_ALLOW_WALLET_CREATE=false`.
- If the account already exists and no local key file is present, set `CROSSCOMPUTE_AGENT_KEY=cc_agent_...`.

## 3) Required Runtime State

Persist these files locally (do not rotate every run):

- `base-wallet.json` (wallet private key, if env key not supplied)
- `crosscompute-agent-key.json` (`cc_agent_*` key returned on first registration)

If wallet is newly generated and unfunded, ask owner to fund:

- `>= 0.1 USDC` on Base mainnet
- small ETH gas on Base mainnet

## 4) API Contract (Minimal)

- Register: `POST /api/agents/register`
- Usage: `GET /api/agents/usage`
- Topup: `POST /api/agents/topup`
- Model discovery: `GET /v1/models`
- Inference: `POST /v1/chat/completions`

Auth:

- `Authorization: Bearer cc_agent_...`

Top-up unit (default):

- `$0.10` -> `10 credits`

OpenAI compatibility contract:

- `/v1/models` returns a local OpenAI-style model list (not passthrough from one upstream provider).
- `/v1/chat/completions` accepts:
  - `role: "developer"` (normalized server-side to `system` when needed)
  - content parts such as `input_text` / `input_image`
  - `max_completion_tokens` (normalized per provider)

Recommended minimal client flow:

1. `GET /v1/models`
2. pick one returned `data[].id` (or use `auto/cheap/medium/premium`)
3. `POST /v1/chat/completions`

## 4.1) Routing Profiles and Current Runtime Settings (Agent-Facing)

For `POST /v1/chat/completions`, `model` accepts either:

- Routing profile alias (recommended for autonomous agents):
  - `auto` (default adaptive routing)
  - `cheap` (cost-first)
  - `medium` (balanced)
  - `premium` (quality-first)
- Explicit model ID (deterministic):
  - `openai/gpt-5-mini`
  - `anthropic/claude-sonnet-4-6`
  - `deepseek-chat`
  - `qwen/qwen-plus`

Legacy aliases accepted:

- `eco -> cheap`
- `balanced -> medium`
- `blockrun/<profile>` (for compatibility)

Current server-side routing knobs (for operator visibility):

- `PROXY_ROUTING_DEFAULT_PROFILE=auto`
- `PROXY_ROUTING_MAX_FALLBACKS=5`
- `PROXY_ROUTING_ENABLE_RUNTIME_HEALTH=true`
- `PROXY_ROUTING_CIRCUIT_BREAKER_FAILURES=3`
- `PROXY_ROUTING_CIRCUIT_BREAKER_COOLDOWN_MS=120000`
- `PROXY_ROUTING_HEALTH_ALPHA=0.2`
- `PROXY_ROUTING_CHEAP_MAX_USD=0` (disabled)
- `PROXY_ROUTING_MEDIUM_MAX_USD=0` (disabled)
- `PROXY_ROUTING_PREMIUM_MAX_USD=0` (disabled)
- `PROXY_ROUTING_EXPLORATION_EPSILON=0` (disabled)

Important model naming note:

- Anthropic canonical IDs should use hyphen format (`claude-sonnet-4-6`), not dot format (`claude-sonnet-4.6`).

Recommended profile examples:

```bash
# cost-first
curl -sS https://www.crosscompute.io/v1/chat/completions \
  -H "Authorization: Bearer cc_agent_xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"cheap","stream":false,"messages":[{"role":"user","content":"Summarize this short text."}]}'

# balanced
curl -sS https://www.crosscompute.io/v1/chat/completions \
  -H "Authorization: Bearer cc_agent_xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"medium","stream":false,"messages":[{"role":"user","content":"Draft a product PRD with tradeoffs."}]}'

# quality-first
curl -sS https://www.crosscompute.io/v1/chat/completions \
  -H "Authorization: Bearer cc_agent_xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"premium","stream":false,"messages":[{"role":"user","content":"Reason carefully and provide final answer only."}]}'
```

Routing and billing observability headers to read on each response:

- `x-crosscompute-routing-profile`
- `x-crosscompute-routing-tier`
- `x-crosscompute-routing-budget`
- `x-crosscompute-routing-version`
- `x-crosscompute-routing-intelligence`
- `x-crosscompute-routing-intelligence-session`
- `x-crosscompute-routing-intelligence-request-id`
- `x-crosscompute-routed-model`
- `x-crosscompute-provider`
- `x-crosscompute-price-rule`
- `x-crosscompute-billed-credits`

Important:

- Do not send `x-crosscompute-routing-profile` in request headers.
- To request cheap routing, set `model: "cheap"` in request JSON body.

## 5) Read-Only vs Charging Operations

- Read-only or non-payment actions:
  - `POST /api/agents/register`
  - `GET /api/agents/usage`
  - `POST /v1/chat/completions` (consumes existing credits only)
- Charging action:
  - `POST /api/agents/topup` (x402 challenge-response payment)

## 6) x402 Behavior You Should Assume

When topup is needed:

1. First topup call returns `HTTP 402 payment-required`.
2. Agent signs challenge using local Base wallet.
3. Agent resubmits topup with payment signature header.
4. Agent receives `200` and captures `topup.txHash`.

Do not re-implement custom payment protocol if x402 libs are available.
Use the quickstart script logic directly.
Do not mutate challenge fields (especially `network`, `payTo`, `price`) before signing.

Important:

- `HTTP 402 {}` can mean either "no payment header" or "invalid payment payload".
- Do not treat repeated `402 {}` as proof that server ignored headers.
- Check response headers:
  - `x-crosscompute-payment-header-present`
  - `x-crosscompute-payment-header-kind`
- Confirm health diagnostics:
  - `/health -> paymentChannels.x402.facilitatorAuthMode`
  - `/health -> paymentChannels.x402.coinbaseHelperRequired`

## 7) Low-Credit Policy

- Poll usage every `5-15` minutes.
- If `remainingCredits <= 20`, auto-topup once.
- If topup fails, alert owner with wallet address.
- If `remainingCredits <= 5`, raise critical alert.

Owner alert template:

```text
CrossCompute credit is low.
remainingCredits=<VALUE>
autoTopup=<success|failed>
wallet=<BASE_ADDRESS>
```

## 8) Reference Links

- Skill: `https://www.crosscompute.io/agent-skill.md`
- Parameter registry: `https://www.crosscompute.io/api-parameters.md`
- Crawler access policy: `https://www.crosscompute.io/crawler-access-policy.md`
- Quickstart script: `https://www.crosscompute.io/examples/crosscompute-agent-quickstart.mjs`
- Trust policy: `https://www.crosscompute.io/.well-known/agent-trust-policy.json`
- Security contact: `https://www.crosscompute.io/.well-known/security.txt`
- OpenAPI: `https://www.crosscompute.io/openapi.json`
- LLM index: `https://www.crosscompute.io/llms.txt`
- Health: `https://www.crosscompute.io/health`