mnemospark Lite for OpenClaw#

Use this skill to operate mnemospark-lite from OpenClaw.

mnemospark-lite gives any agent access to cloud storage through a simple paid HTTP workflow. Agents can upload files, list stored files, delete files, and generate shareable links that can be passed to another agent or a human. Humans can use the web app at https://app.mnemospark.ai/mnemospark-lite to view files, download them, delete them, and create share links from a friendly UI. It’s the same storage system, designed to work cleanly for both agents and people. Files are retained for 30 days and then automatically deleted.

Workflow summary#

Support these mnemospark-lite operations:

• upload a file and mint its share URL
• list uploads visible to the payer wallet scope
• fetch download details for a specific upload
• mint a 24-hour share URL for an existing upload
• delete one or more uploads

Use these endpoints as needed:

• POST /api/mnemospark-lite/upload
• POST /api/mnemospark-lite/upload/complete
• GET /api/mnemospark-lite/uploads
• GET /api/mnemospark-lite/download/{uploadId}
• POST /api/mnemospark-lite/share
• POST /api/mnemospark-lite/delete

Inputs you need#

Collect the minimum inputs for the requested operation.

Common inputs:

• MNEMOSPARK_API_BASE_URL=https://api.mnemospark.ai
• a funded x402-capable payer or existing mnemospark-compatible wallet

Upload inputs:

• file path on disk
• tier: one of 10mb, 100mb, 500mb, 1gb, 2gb, 3gb
• contentType
• file size in bytes

Bearer-scoped read/write inputs after upload:

• Authorization: Bearer <token>
• use list_scope_bearer from the paid upload flow when available

Entity inputs:

• uploadId for download/share/delete operations
• one or more uploadId values for delete

OpenClaw environment hints#

When running inside OpenClaw:

• if the mnemospark plugin is installed, the wallet key usually exists at /home/ubuntu/.openclaw/mnemospark/wallet/wallet.key
• some older or local setups may also have a legacy Blockrun wallet path, but do not assume it is the active mnemospark wallet
• for the plugin CLI, prefer an absolute invocation like /usr/bin/node /home/ubuntu/.openclaw/extensions/mnemospark/dist/cli.js wallet
• do not rely on npx mnemospark or cwd-sensitive paths when local install state may have drifted
• if you use the Python x402 client path, install the EVM extras, not only the base package: pip install 'x402[evm]'

Canonical upload flow#

When the user wants to upload a file, use this exact flow.

1) Probe the paid upload endpoint#

Probe POST ${MNEMOSPARK_API_BASE_URL}/api/mnemospark-lite/upload without payment first when you need the x402 challenge.

Request body:

json

{
  "filename": "example.txt",
  "contentType": "text/plain",
  "tier": "10mb",
  "size_bytes": 12
}

Read PAYMENT-REQUIRED or x-payment-required, base64-decode it, and preserve the advertised payment requirement.

The 402 JSON body may also include:

• resource.url
• accepts
• extensions.bazaar

For bazaar indexing and compatibility, preserve the advertised requirement and echo extensions.bazaar into the x402 PaymentPayload when your client supports that.

2) Submit the paid upload request#

Retry the same POST /upload request with:

• Content-Type: application/json
• PAYMENT-SIGNATURE: <base64-json> or x-payment: <base64-json>

Prefer PAYMENT-SIGNATURE unless the runtime only supports x-payment.

Response fields can include:

• data.uploadId
• data.uploadUrl
• data.completion_token
• data.list_scope_bearer
• data.publicUrl
• data.siteUrl
• metadata.payment.status
• metadata.payment.transactionHash
• metadata.payment.success

3) Handle settlement polling correctly#

The paid POST /upload may return:

• 200 immediately, or
• 202 with error: settlement_pending

If it returns 202:

• retry the same paid request
• reuse the exact same payment payload
• do not regenerate, normalize, shrink, or rebuild the payment JSON
• poll about every 2 seconds
• use a timeout of about 60 seconds

4) Upload the file bytes#

Send the file bytes with PUT to data.uploadUrl.

Example:

bash

curl -T "example.txt" \
  -H "Content-Type: text/plain" \
  "<uploadUrl>"

5) Complete the upload#

Call POST ${MNEMOSPARK_API_BASE_URL}/api/mnemospark-lite/upload/complete with only:

json

{
  "uploadId": "<uploadId>",
  "completion_token": "<completion_token>"
}

Rules:

• do not send a payment header to /upload/complete
• send only uploadId and completion_token
• if the service returns 202, poll every few seconds until 200 or timeout
• use a timeout of about 45–60 seconds

Successful completion should expose:

• data.upload.publicUrl
• data.upload.siteUrl
• data.upload.status

6) Verify at least one read path#

After completion, verify at least one bearer-scoped read path:

• GET /api/mnemospark-lite/uploads
• GET /api/mnemospark-lite/download/{uploadId}

Use Authorization: Bearer <list_scope_bearer>.

This confirms the upload is visible to the payer-scoped APIs and can mint or expose a download URL.

Critical reliability rule#

When running under OpenClaw, use the x402 client-generated payload flow rather than hand-built JSON.

Use the exact payment payload generated by the x402 client library and base64-encode that JSON as-is.

Do not:

• rewrite the payload into a different version
• convert eip155:8453 into base
• inject or remove fields unless you are explicitly debugging backend compatibility
• rebuild a smaller payload by hand when the x402 client already returned the full object

Use the raw x402 client payload for the paid /upload request, retry the same paid request on 202 settlement_pending with the same payload, then call /upload/complete with only uploadId and completion_token.

Also capture these fields from the paid /upload response when present:

• metadata.payment.status
• metadata.payment.transactionHash
• metadata.payment.success

Those fields are the cleanest proof that facilitator settlement succeeded.

Expected x402 payload shape#

Successful runs used an x402-generated payload containing at least:

• x402Version
• accepted
• resource
• payload.signature
• payload.authorization

Example shape:

json

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "<asset>",
    "payTo": "<recipient>",
    "amount": "<amount>",
    "maxTimeoutSeconds": 3600,
    "extra": {
      "name": "USD Coin",
      "version": "2"
    }
  },
  "resource": {
    "url": "https://api.mnemospark.ai/api/mnemospark-lite/upload",
    "mimeType": "application/json",
    "description": "mnemospark-lite upload"
  },
  "payload": {
    "signature": "<eip3009-signature>",
    "authorization": {
      "from": "<payer-wallet>",
      "to": "<recipient>",
      "value": "<amount>",
      "validAfter": "<unix-seconds>",
      "validBefore": "<unix-seconds>",
      "nonce": "<bytes32>"
    }
  }
}

Treat later backend normalization or enrichment as a server concern, not a reason to mutate the client payload.

List uploads#

When the user wants to see uploads for the payer scope, call:

• GET ${MNEMOSPARK_API_BASE_URL}/api/mnemospark-lite/uploads
• Authorization: Bearer <token>

You typically receive the token as list_scope_bearer from the paid upload flow.

Expect data.uploads[] fields such as:

• id
• filename
• contentType
• tier
• maxSize
• actualSize
• publicUrl
• status
• pricePaid
• expiresAt
• createdAt

Notes:

• bearer scope is tied to the payer wallet
• publicUrl may be null until /upload/complete
• treat bearer tokens as credentials and store them appropriately for the runtime

Download an upload#

When the user wants download detail or a short-lived download URL, call:

• GET ${MNEMOSPARK_API_BASE_URL}/api/mnemospark-lite/download/<uploadId>
• Authorization: Bearer <token>

Expect:

• data.upload
• data.upload.downloadUrl when the upload is in a downloadable state

Notes:

• bearer access is wallet-scoped
• download URLs are short-lived presigned URLs
• do not assume the download URL is permanent

Mint a share URL#

When the user wants a 24-hour share link for an existing upload, call:

• POST ${MNEMOSPARK_API_BASE_URL}/api/mnemospark-lite/share
• Authorization: Bearer <token>
• Content-Type: application/json

Body:

json

{
  "uploadId": "<uploadId>"
}

Expect:

• data.shareUrl
• data.expiresAt

Notes:

• bearer access is wallet-scoped to the same payer scope as list/download
• the share URL is anonymous and expires after 24 hours
• recipients use the app flow to exchange the token for a short-lived download URL

Delete uploads#

When the user wants to delete one or more uploads, call:

• POST ${MNEMOSPARK_API_BASE_URL}/api/mnemospark-lite/delete
• Authorization: Bearer <token>
• Content-Type: application/json

Body:

json

{
  "uploadIds": ["<uploadId1>", "<uploadId2>"]
}

Expect:

• data.deleted
• data.results[] per upload ID

Notes:

• deletes are wallet-scoped
• process each result independently
• re-run GET /uploads to confirm removals

Output expectations#

Return or persist the most useful fields for the active task:

• uploadId
• publicUrl
• siteUrl
• shareUrl when minted separately
• list_scope_bearer
• metadata.payment.status when present
• metadata.payment.transactionHash when present
• metadata.payment.success when present