---
name: x402drop-agent-api
description: Create temporary x402drop storage through its x402 V2 agent HTTP API, upload files, resume uploads, and return expiring share links.
---

# x402drop Agent API

Base URL: https://x402drop.com

For metadata, analytics, or quotes, use the scoped MCP connection at https://x402drop.com/api/mcp/docs. For paid uploads, read https://x402drop.com/docs#agent-api.

## Paid upload

1. Prepare files with name, positive integer sizeBytes, and mimeType, plus positive integer durationSeconds. Limits: 1–1000 files per drop, 5 GB per file, 10 GB per drop, and 90 days maximum storage duration. Request live pricing.
2. Generate a private random UUID as Idempotency-Key. POST files and duration to /api/agent/drops with that header. Read the x402 V2 402 response and PAYMENT-REQUIRED.
3. Use an authorized wallet client to sign one live accepts requirement. Retry the same body with PAYMENT-SIGNATURE and the original Idempotency-Key. That key is mandatory on the paid retry; using it from the initial challenge is recommended.
4. Retain PAYMENT-RESPONSE, paymentId, and returned metadata. Upload using uploadUrls, then POST /api/agent/drops/{slug}/complete with Authorization: Bearer <uploadToken>.
5. For uploadSetupPending or expired upload URLs, POST /api/agent/drops/{slug}/resume with the uploadToken. Multipart operations use POST /api/agent/drops/{slug}/multipart. Read the agent API guide for their payloads.
6. Return the server's shareUrl or downloadUrl and paid expiration.

## Recovery

Preserve paymentId and the same body, proof, and Idempotency-Key on paid retries. For HTTP 202 with paymentPending, report the pending state and wait for reconciliation. Do not create or sign a replacement payment while it is pending. HTTP 409 signals conflicting request identity. For HTTP 503, follow retryable and preserve the original paid request. Resume incomplete uploads with their existing token rather than creating another paid drop.

## Boundaries

Paid REST creation needs no MCP API key. Upload tokens and scoped MCP keys serve different endpoints. Quotes authorize no charge. EVM and Solana sign-in are available; payment availability comes only from the live accepts array, reflecting merchant configuration and facilitator support. Wallet signing stays outside MCP.

Downloads stop at paid expiration. Cleanup follows the configured job without a promised deletion interval. Upload URLs last up to an hour and are capped by drop expiration.