musicwire

# Musicwire

Musicwire is a deterministic MusicXML validation, MuseScore rendering, automated QC, and attribution API for agents. It does not compose music or invoke a server-side LLM. MCP clients such as Claude Code and Cursor can use the API through the `musicwire-mcp` stdio server in `mcp/`; see `mcp/README.md` for install, configuration, and payment behavior.

## Agent quickstart

Get a static MusicXML authoring prompt and quality bar at no cost:

```sh
curl 'http://localhost:8787/v1/compose-guide?style=waltz&key=F%20major&tempo=84'
```

Request a validation quote before rendering. The response is `402 Payment Required` until an x402 buyer supplies a payment authorization valid for the network this deployment advertises (Base Sepolia by default, Base mainnet in production):

```sh
curl -X POST http://localhost:8787/v1/validate \
  -H 'content-type: application/json' \
  --data '{"musicxml":"<?xml version=\"1.0\"?><score-partwise version=\"4.0\">...</score-partwise>"}'
```

Submit an asynchronous render. MusicXML, `NOTICE.txt`, and `receipt.json` are always returned. `svg` and `png` results are page sets.

```sh
curl -X POST http://localhost:8787/v1/render \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: a-stable-request-id' \
  --data @request.json

# request.json: {"musicxml":"...","formats":["pdf","svg","mp3"],"constraints_check":{"tempo":84}}
# Poll the returned job_id without charge:
curl http://localhost:8787/v1/jobs/JOB_ID
```

`POST /v1/validate` accepts raw `application/xml` bytes or a JSON `musicxml` string. `POST /v1/render` requires JSON with a non-empty `formats` array and accepts optional `constraints_check`. Client filesystem paths and compressed input are rejected.

## How agents pay

Local and stub x402 runs default to **test USDC on Base Sepolia** (`eip155:84532`). The production deployment is pinned to **Base mainnet** (`eip155:8453`) and creates or reuses its named CDP Server Wallet from the supplied credentials. Do not send funds to a local or test deployment.

Run a payment-enabled server by sourcing local CDP credentials without printing them. The durable local database stores only the named wallet identity and receiving address, never the wallet secret.

```sh
set -a
. "$HOME/.config/ai-keys.env"
set +a
MUSICWIRE_PAYMENT_MODE=x402 \
MUSICWIRE_PUBLIC_BASE_URL='https://musicwire.example' \
ARTIFACT_SIGNING_SECRET='replace-with-a-long-random-secret' \
npm start
```

The following `curl` request is the discovery step. It returns the exact `Payment-Required` header and JSON quote, including the output schema, with no payment authorization or settlement.

```sh
export MUSICWIRE_URL='https://musicwire.example'
curl -sS -D /tmp/musicwire-402.headers -o /tmp/musicwire-402.json \
  -X POST "$MUSICWIRE_URL/v1/render" \
  -H 'content-type: application/json' \
  -H 'Idempotency-Key: agent-render-001' \
  --data-binary @request.json
```

For Coinbase Agentic Wallet CLI, fund its Base Sepolia wallet with test USDC, authenticate Awal, inspect the quote, then send the identical JSON request. The `max-amount` guard is in USDC atomic units.

```sh
REQUEST_JSON="$(tr -d '\n' < request.json)"
npx awal x402 details "$MUSICWIRE_URL/v1/render" -X POST
npx awal x402 pay "$MUSICWIRE_URL/v1/render" \
  -X POST \
  -d "$REQUEST_JSON" \
  -h '{"content-type":"application/json","Idempotency-Key":"agent-render-001"}' \
  --max-amount 250000 \
  --json
```

`@x402/fetch` is the programmatic buyer used by the Base Sepolia E2E test. Set `MUSICWIRE_X402_E2E=1`, fund the named `musicwire-x402-e2e-buyer` account with at least 0.25 test USDC, then run `npm run test:x402-e2e`.

For the independent Rust client, use a throwaway Base Sepolia key only:

```sh
X402_PRIVATE_KEY="$TESTNET_PRIVATE_KEY" x402curl --x402-rpc-url https://sepolia.base.org -X POST -H 'content-type: application/json' --data-binary @request.json "$MUSICWIRE_URL/v1/render"
```

Compatibility note: `x402curl 0.2.0` was installed and tested. It receives the v2 quote and signs the retry, but that v2 signed retry does not complete with the CDP facilitator, so no job or settlement is reached. The Coinbase `@x402/fetch` E2E is the required payment proof for this phase.

An `Idempotency-Key` header replays the original paid outcome and cannot create a second charge. A render key replays for 24 hours only when the same verified payer submits the same render request context; a validation key replays indefinitely only when the same verified payer submits the same MusicXML request context. Replay hashing sorts object keys and the unordered render `formats` selection, since format order cannot alter requested work; MusicXML and any order-sensitive input remain unchanged. A key from another payer never resolves a retained result. Musicwire verifies an authorization before work begins, then calls the facilitator settlement endpoint only after server-side QC passes. A QC failure returns `failed_not_charged` and a receipt with `tx_hash: null`. Before every settle attempt Musicwire durably records the payment as `settlement_pending` alongside the QC-passed artifacts, so a crash mid-settlement resumes as reconciliation on restart instead of a false `failed_not_charged`. If the facilitator settlement outcome is unknown after QC passes, the result is delivered with `payment.status: "settlement_pending"` and `tx_hash: null`, and Musicwire retries the settlement check in the background until it is confirmed or definitively failed; the EIP-3009 authorization nonce makes a reconciliation retry unable to charge twice. When a reconciliation retry is refused by the facilitator, Musicwire checks ground truth on the configured network (`X402_RPC_URL`, default `https://sepolia.base.org`, and `https://mainnet.base.org` in production): a consumed authorization resolves to `settled` with the located transaction hash, an authorization provably unused past its expiry resolves to `failed_not_charged`, and anything else stays `settlement_pending`. A definitive facilitator refusal on `POST /v1/validate` returns `502 payment_settlement_failed` with no charge. A request to a priced route without a `Payment-Signature` receives the `402` challenge before payload validation, even when its body is empty, missing, or malformed, so discovery probes can read the quote; payload validation and its not-charged failure codes apply only once a payment is presented, while oversized and compressed bodies are still rejected at the transport layer. A paid `POST /v1/render` with an invalid score returns a coarse 422 without charging and without line-level diagnostics; those are the paid `POST /v1/validate` product.

## Request and response schemas

MusicXML supplied in a JSON request body must be a UTF-8 string. Render requests must be JSON and name at least one requested artifact format.

```json
// POST /v1/validate
{ "musicxml": "<score-partwise version=\"4.0\">...</score-partwise>" }

// 402 payment quote (also represented in the Payment-Required header)
{ "x402Version": 2, "accepts": [{ "scheme": "exact", "network": "eip155:84532", "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "amount": "250000", "payTo": "0x2855fB60E630d6A9Ebe0beAE1E1d6392F630F86f" }], "quote": { "currency": "USDC", "price_usd": "0.25", "settlement": "after_qc_pass", "output_schema": { "completed_job_fields": ["qc", "artifacts", "receipt"] } } }

// 200 validation response after QC and settlement
{ "valid": true, "errors": [], "price_usd": "0.10", "payment": { "status": "settled" }, "receipt": { "tx_hash": "0x...", "amount_usd": "0.10", "amount_atomic": "100000", "network": "eip155:84532" } }

// POST /v1/render
{ "musicxml": "<score-partwise version=\"4.0\">...</score-partwise>", "formats": ["pdf", "svg", "mp3"], "constraints_check": { "tempo": 84, "duration_seconds": 30, "key_fifths": -1, "mode": "minor" } }

// 202 render response. The verified authorization is not yet settled.
{ "job_id": "uuid", "status": "queued", "estimated_seconds": 30, "price_usd": "0.25", "payment": { "status": "verified_pending_qc", "capture_policy": "capture_only_after_qc_pass" }, "poll_url": "/v1/jobs/uuid", "provenance": { "receipt_id": "uuid", "verification_url": "https://musicwire.example/v1/provenance/verify" } }

// GET /v1/jobs/{id}
{ "job_id": "uuid", "status": "completed", "facts": { "partCount": 1, "tempo": 84, "key": { "fifths": -1, "mode": "minor" }, "scoreDurationSeconds": 30 }, "qc": { "status": "passed" }, "error": null, "payment": { "status": "settled" }, "receipt": { "status": "settled", "tx_hash": "0x...", "amount_usd": "0.25", "amount_atomic": "250000", "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e", "network": "eip155:84532", "pay_to": "0x2855..." }, "provenance": { "receipt_id": "uuid", "verification_url": "https://musicwire.example/v1/provenance/verify" }, "expires_at": "2026-01-01T00:00:00.000Z", "artifacts": [{ "name": "receipt.json", "sha256": "hex", "bytes": 1234, "url": "/v1/artifacts/uuid/receipt.json?expires=...&token=..." }] }

// POST /v1/provenance/verify - free, no payment required
{ "sha256": "64-character-lowercase-hex-sha-256-of-an-artifact-file" }

// 200 when the hash matches a Musicwire-rendered artifact; unknown hashes return { "rendered_by_musicwire": false }
{ "rendered_by_musicwire": true, "receipt_id": "uuid", "rendered_at": "2026-01-01T00:00:00.000Z", "artifact": { "name": "score.mp3", "sha256": "hex", "bytes": 1234 }, "receipt": { "receipt_id": "uuid", "rendered_by": "Musicwire", "verification_url": "https://musicwire.example/v1/provenance/verify", "rendered_at": "2026-01-01T00:00:00.000Z", "artifacts": [{ "name": "score.mp3", "sha256": "hex", "bytes": 1234 }], "signature": "base64url", "signature_algorithm": "HMAC-SHA-256" } }

// POST /reviews - tx_hash must be from a settled Musicwire render payment
{ "tx_hash": "0x...", "rating": 5, "comment": "Accurate output and clean artifacts." }

// 201 review response. The transaction anchor is public and independently verifiable on Base S