Make music. Then let someone hear it.

[ QUICKSTART ]

Connect, request, pay, receive, listen.

1. Connect your agent

   Use the MCP server when your agent supports MCP. Add this connection to its project configuration, then configure that client with a funded x402 buyer wallet. The public service URL is explicit so your agent reaches musicwire.

   {
     "mcpServers": {
       "musicwire": {
         "command": "npx",
         "args": ["-y", "musicwire-mcp"],
         "env": { "MUSICWIRE_API_URL": "https://musicwire.5432wire.com" }
       }
     }
   }

   Hosted MCP clients such as Claude Connectors and Smithery connect over Streamable HTTP at the same domain. Musicwire does not hold a buyer wallet for that endpoint. Paid tools quote with the same x402 challenge as the HTTPS API.

   https://musicwire.5432wire.com/mcp

   For plain HTTPS, read the live machine-readable manifest first:

   curl https://musicwire.5432wire.com/manifest

2. Ask for a complete score

   Tell the agent what to write, or provide your own MusicXML. The free compose guide gives an agent a versioned authoring prompt and quality bar.

   curl 'https://musicwire.5432wire.com/v1/compose-guide?style=waltz&key=C%20major&tempo=96'

3. Request a render

   Ask for mp3 so a human can listen and midi so they can continue editing. The worked examples below use those formats.

4. Authorize the quoted payment

   A paid request first receives an exact x402 quote. An x402-aware MCP client handles that retry. With plain HTTPS, use an x402 buyer to sign and retry the identical request.

5. Receive and listen

   Poll the returned job until it is completed. Open the MP3 link in a browser or audio player. Download the MIDI into a DAW or notation editor. Keep the receipt with the final work.

<?xml version="1.0" encoding="UTF-8"?>
<score-partwise version="4.0">
  <work><work-title>Small Steps</work-title></work>
  <identification><creator type="composer">Your agent</creator></identification>
  <part-list>
    <score-part id="P1"><part-name>Piano</part-name></score-part>
  </part-list>
  <part id="P1">
    <measure number="1">
      <attributes><divisions>1</divisions><key><fifths>0</fifths><mode>major</mode></key><time><beats>4</beats><beat-type>4</beat-type></time><clef><sign>G</sign><line>2</line></clef></attributes>
      <direction placement="above"><direction-type><metronome><beat-unit>quarter</beat-unit><per-minute>96</per-minute></metronome></direction-type><sound tempo="96"/></direction>
      <note><pitch><step>C</step><octave>5</octave></pitch><duration>1</duration><type>quarter</type></note>
      <note><pitch><step>E</step><octave>5</octave></pitch><duration>1</duration><type>quarter</type></note>
      <note><pitch><step>G</step><octave>5</octave></pitch><duration>1</duration><type>quarter</type></note>
      <note><rest/><duration>1</duration><type>quarter</type></note>
    </measure>
    <measure number="2">
      <note><pitch><step>G</step><octave>5</octave></pitch><duration>1</duration><type>quarter</type></note>
      <note><pitch><step>E</step><octave>5</octave></pitch><duration>1</duration><type>quarter</type></note>
      <note><pitch><step>D</step><octave>5</octave></pitch><duration>1</duration><type>quarter</type></note>
      <note><pitch><step>C</step><octave>5</octave></pitch><duration>1</duration><type>quarter</type></note>
      <barline location="right"><bar-style>light-heavy</bar-style></barline>
    </measure>
  </part>
</score-partwise>

Render, pay, and get the result

Create the JSON request from the file, then use your x402 buyer to submit it. Keep one idempotency key for safe retries of this same request.

node -e 'const fs=require("fs"); console.log(JSON.stringify({musicxml:fs.readFileSync(process.argv[1],"utf8"),formats:["mp3","midi"]}))' solo-piano.musicxml > request.json

npx awal x402 pay https://musicwire.5432wire.com/v1/render \
  -X POST -d "$(cat request.json)" \
  -h '{"content-type":"application/json","Idempotency-Key":"solo-piano-001"}' \
  --max-amount 1000000 --json

The successful submission returns a job immediately. Its fields look like this:

{
  "job_id": "a-render-job-id",
  "status": "queued",
  "estimated_seconds": 25,
  "price_usd": "live quoted price",
  "payment": { "status": "verified_pending_qc", "capture_policy": "capture_only_after_qc_pass" },
  "poll_url": "/v1/jobs/a-render-job-id"
}

Poll until status is completed, then open the .mp3 artifact URL. That is the moment the human hears the piece.

curl https://musicwire.5432wire.com/v1/jobs/a-render-job-id

<?xml version="1.0" encoding="UTF-8"?>
<score-partwise version="4.0">
  <work><work-title>Two Voices</work-title></work>
  <identification><creator type="composer">Your agent</creator></identification>
  <part-list>
    <score-part id="P1"><part-name>Violin</part-name></score-part>
    <score-part id="P2"><part-name>Violoncello</part-name></score-part>
  </part-list>
  <part id="P1"><measure number="1">
    <attributes><divisions>1</divisions><key><fifths>0</fifths><mode>major</mode></key><time><beats>4</beats><beat-type>4</beat-type></time><clef><sign>G</sign><line>2</line></clef></attributes>
    <direction placement="above"><direction-type><metronome><beat-unit>quarter</beat-unit><per-minute>84</per-minute></metronome></direction-type><sound tempo="84"/></direction>
    <note><pitch><step>E</step><octave>5</octave></pitch><duration>2</duration><type>half</type></note>
    <note><pitch><step>G</step><octave>5</octave></pitch><duration>2</duration><type>half</type></note>
    <barline location="right"><bar-style>light-heavy</bar-style></barline>
  </measure></part>
  <part id="P2"><measure number="1">
    <attributes><divisions>1</divisions><key><fifths>0</fifths><mode>major</mode></key><time><beats>4</beats><beat-type>4</beat-type></time><clef><sign>F</sign><line>4</line></clef></attributes>
    <note><pitch><step>C</step><octave>3</octave></pitch><duration>2</duration><type>half</type></note>
    <note><pitch><step>G</step><octave>2</octave></pitch><duration>2</duration><type>half</type></note>
    <barline location="right"><bar-style>light-heavy</bar-style></barline>
  </measure></part>
</score-partwise>

The request is the same. The service automatically applies the ensemble price when the score has more than one part.

node -e 'const fs=require("fs"); console.log(JSON.stringify({musicxml:fs.readFileSync(process.argv[1],"utf8"),formats:["mp3","midi"]}))' violin-cello.musicxml > request.json

npx awal x402 pay https://musicwire.5432wire.com/v1/render \
  -X POST -d "$(cat request.json)" \
  -h '{"content-type":"application/json","Idempotency-Key":"violin-cello-001"}' \
  --max-amount 1000000 --json

When it completes, play the .mp3 and import the .midi to continue editing the score.

[ AUDIO QUALITY ]

Natural endings are allowed. Extra audio is not.

For humans

Musicwire compares the MP3 length with the score's playback length. MuseScore adds a small natural ending after the final note, so every MP3 has a three-second allowance plus 10% of the score duration. Scores that name a sustained instrument or section, including violin, cello, Wind, Woodwind, Brass, Strings, organ, or voice, receive up to 3.25 seconds instead.

This only allows a normal release tail. Audio that runs longer than that limit still fails quality control, returns failed_not_charged, and is never captured.

For agents

Declare each part with a truthful part-name or instrument-name. Musicwire uses those declared instruments to select the bounded tail allowance, then rejects any MP3 longer than score_duration + allowance + 10%.

<score-part id="P1">
  <part-name>Violin</part-name>
</score-part>

[ DISCOVERY FLOW ]

Probe, get the 402 challenge, pay, get the result.

For humans

You never need to know the price in advance. Send any request without a payment to POST /v1/validate or POST /v1/render - even with an empty or missing body - and musicwire answers 402 Payment Required with a quote listing the price, network, asset, and receiving address. Pay that quote with any standard x402 client and repeat the request; the body is only validated after a payment is presented, and a rejected body never charges you.

For agents

# Hosted MCP: initialize and list tools are free. A paid tool call
# without Payment-Signature returns HTTP 402 with the same quote as
# the HTTPS API. Retry the identical MCP request after signing.
curl -si -X POST https://musicwire.5432wire.com/mcp \
  -H 'accept: application/json, text/event-stream' \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# 1. Probe a priced route. Any unpaid request returns the 402 challenge;
#    the Payment-Required header carries the machine-readable quote.
curl -si -X POST https://musicwire.5432wire.com/v1/validate

# 2. Or read the requirements with standard x402 buyer tooling.
npx -y awal x402 details https://musicwire.5432wire.com/v1/validate --json

# 3. Sign the quote and retry with payment in one step.
npx -y awal x402 pay https://musicwire.5432wire.com/v1/validate \
  -X POST -d '{"musicxml":"<your complete MusicXML document>"}'

# 4. Read the result. 200 means valid and settled after QC; 422 with
#    status failed_not_charged means QC failed and nothing was charged.

The same flow applies to POST /v1/render. A probe without a readable score is quoted the solo base price; probing with your real request body returns the exact price tier your payment must match.