Vaultline

Use when an agent needs to store, retrieve, list, inspect, or delete files through Vaultline, or when it needs to choose between open and private storage tiers, construct the required wallet-auth headers for private objects, or follow the x402 pay-and-retry flow for uploads and downloads. Also use when explaining that encrypted storage is coming soon but not live.

Use this skill to work with the Vaultline API correctly and consistently.

Quick workflow

1. Decide the storage tier.
2. Build the exact file path/key.
3. Upload, read, head, list, or delete with the correct headers.
4. For paid operations, follow the x402 pay-and-retry flow.
5. For private objects, require wallet-auth headers before access.
6. Treat encrypted storage as coming soon, not live.

Tier decision

• Use open for shared/public-by-key files.
• Use private for wallet-restricted files.
• Do not use encrypted as a live tier yet.

Read references/pricing-and-tier-selection.md when you need pricing, tradeoffs, or help choosing a tier.

Core rules

• Default to open if no tier is specified.
• Require x-storage-tier: private for private uploads.
• Require wallet-auth headers for private upload, read, head, delete, and any list call that should reveal private objects.
• Treat open files as readable by anyone who knows the path and satisfies any payment requirement.
• Keep the original request intact when retrying after 402 payment negotiation.
• Preserve content-type and content-length on uploads.
• Do not claim encrypted/ciphertext storage exists yet.

Private auth rules

For private operations, send:

• x-auth-wallet
• x-auth-timestamp
• x-auth-signature

The signature must cover:

• HTTP method
• request path
• wallet
• timestamp

Read references/api-examples.md for the exact auth message format and request examples.

Pay-and-retry rules

For paid uploads or large paid reads:

1. Send the request normally.
2. If the server returns 402, parse the payment-required header.
3. Create/sign the x402 payment payload.
4. Retry the same request with the payment header.
5. Expect the normal route response.

Task patterns

Upload a shared file

• Use open.
• Upload normally.
• If the server returns 402, pay and retry.

Upload a private file

• Use private.
• Attach wallet-auth headers.
• Optionally attach x-owner-wallet and x-allowed-wallets.
• If the server returns 402, pay and retry.

Read a private file

• Always attach wallet-auth headers first.
• Expect 401 when auth headers are missing or invalid.
• Expect 403 when the wallet is authenticated but not authorized.
• If authorized and the read is billable, pay and retry after 402.

Explain the product tiers

• Say open is live.
• Say private is live.
• Say encrypted is coming soon.
• Frame them as: sharing -> ownership -> maximum privacy.