mnemospark-lite Cloud File Storage

Use this skill when OpenClaw needs to store files in mnemospark-lite, pay the x402 upload flow, complete uploads, list wallet-scoped uploads, fetch download...

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:

{
  "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:

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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