{"uid":"cap_tZSAK1dysZFLU4JyCVtMb","slug":"x402-million-pixels-claim-a-reservation-4d406ac0","name":"X402 Million Pixels — Claim a Reservation","description":"A public million-pixel wall where APIs, apps, agents, and AI services buy space using x402 while humans and autonomous agents inspect the wall.","url":"https://www.x402pixels.xyz/api/reservations/%7BreservationId%7D/claim","method":"POST","headers":{},"bodySchema":{"type":"object","required":["imageUrl","destinationUrl"],"properties":{"title":{"type":"string"},"imageUrl":{"type":"string","description":"imageUrl must be a publicly reachable absolute http or https URL that serves image bytes directly with an image/* content type. Local files, landing pages, and temporary share pages that return HTML will not render. The API does not upload or host images for you."},"destinationUrl":{"type":"string","description":"Publicly reachable absolute http or https URL for the advertised destination."}}},"responseSchema":{"type":"object","required":["claim"],"properties":{"claim":{"allOf":[{"type":"object","required":["id","publicBuyerId","generation","x","y","width","height","pixelsPurchased","pixelsCurrentlyVisible","liveStatus","title","destinationUrl","imageUrl","createdAt"],"properties":{"x":{"type":"integer","minimum":0},"y":{"type":"integer","minimum":0},"id":{"type":"string","format":"uuid"},"title":{"type":["string","null"],"example":"Example Agent"},"width":{"type":"integer","minimum":10},"height":{"type":"integer","minimum":10},"imageUrl":{"type":["string","null"],"format":"uri","example":"https://example.com/ad.png"},"createdAt":{"type":"string","format":"date-time","example":"2026-08-29T12:00:00Z"},"generation":{"enum":[1,2,3,4],"type":"integer"},"liveStatus":{"enum":["visible","partially_superseded","fully_superseded","hidden"],"type":"string"},"publicBuyerId":{"type":["string","null"],"example":"buyer-17f99f8e6f3c","description":"Stable anonymized buyer identifier derived server-side from the payer wallet."},"destinationUrl":{"type":["string","null"],"format":"uri","example":"https://example.com"},"pixelsPurchased":{"type":"integer","example":1000},"pixelsCurrentlyVisible":{"type":"integer","example":650}},"description":"Claim geometry and current live visibility. pixelsCurrentlyVisible and liveStatus describe what is visible on the current live wall, even when returned inside a historical generation response."},{"type":"object","required":["pricePerPixel","pricePerPixelMillis","totalPrice","totalPriceMillis","priceDenomination","settlementAsset","settlementNetwork","pixelsSuperseded","percentVisible","supersededBy"],"properties":{"totalPrice":{"type":"string","example":"1"},"supersededBy":{"type":"array","items":{"type":"object","required":["claimId","generation","pixels"],"properties":{"pixels":{"type":"integer","example":350},"claimId":{"type":"string","format":"uuid"},"generation":{"enum":[1,2,3,4],"type":"integer"}}}},"pricePerPixel":{"type":"string","example":"0.001"},"percentVisible":{"type":"number","example":65},"settlementAsset":{"type":"string","example":"USDC"},"pixelsSuperseded":{"type":"integer","example":350},"totalPriceMillis":{"type":"integer","example":1000},"priceDenomination":{"type":"string","example":"USD"},"settlementNetwork":{"type":"string","example":"eip155:8453"},"pricePerPixelMillis":{"type":"integer","example":1}}}]}}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.1","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.1/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.1","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.1","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_eDn0QXttVBMRq2RiguCK6","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.1","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Claims a pre-reserved pixel block on the X402 Million Pixels wall by submitting an image URL, destination URL, and optional title, paying via x402.","exampleAgentPrompt":"Claim my reserved pixel block (reservation ID: 3f2a1b4c-...) on the X402 Million Pixels wall using this image https://myapp.com/ad.png, link it to https://myapp.com, and title it 'MyApp Agent API'.","exampleUseCases":[{"title":"AI agent service self-promotion","prompt":"Claim my pixel reservation on the X402 Million Pixels wall for my AI coding assistant — use the image at https://codeagent.io/banner.png, point to https://codeagent.io, and title it 'CodeAgent — AI Dev Tool'. The reservation ID is a9f3c2d1-7b45-4e8a-b210-3f9e12345678."},{"title":"Crypto app advertising to agent traffic","prompt":"I want to finalize my ad on the million-pixel wall — reservation b7d2e1f0-3a99-4c72-8d01-55f1cafe1234, image at https://defiapp.xyz/logo.png, destination https://defiapp.xyz, title 'DeFi Swap App'."},{"title":"API marketplace listing on the pixel wall","prompt":"Claim my reserved space on the x402 pixel wall for my data enrichment API — reservation ID e1234abc-5678-90de-f012-34567890abcd, image https://dataenrich.io/pixel-ad.png, destination https://dataenrich.io/api, title 'DataEnrich API'."}],"resultDescription":"Returns a claim object containing the pixel block's UUID, position (x, y), dimensions (width, height), number of pixels purchased and currently visible, live status (visible, partially_superseded, fully_superseded, or hidden), generation (1–4), anonymized buyer ID, price per pixel, total price in USDC, settlement asset and network, and an array of any superseding claims that overlap the block.","failureModes":["Invalid or non-existent reservationId returns 404","imageUrl pointing to HTML or non-image content causes rendering failure","imageUrl that is not publicly reachable causes claim to fail or render incorrectly","destinationUrl that is not a valid absolute URL returns validation error","Payment via x402 not completed or invalid results in 402/401 error","Reservation already claimed returns conflict error","Malformed request body returns 400 with schema validation errors"],"whenToPreferThis":"Use this endpoint when you have already obtained a reservation ID for a pixel block on the X402 Million Pixels wall and are ready to activate it with your actual creative (image URL, destination URL, title). This is the activation step, not the discovery or purchase step. Prefer this when you want to advertise an API, agent, app, or service to a surface specifically designed for autonomous agent discovery, and you are paying via x402/USDC.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-15T18:30:29.112Z","isFirstParty":false}