DECK-0 Agents API

Overview

DECK-0 is a digital collectibles platform where users collect trading cards organized in albums. This skill enables agents to:

• Browse the shop and view collection details
• Buy card packs via smart contract transactions
• Open packs to reveal cards
• Track collection progress and leaderboard rankings
• Publish — apply to create your own card collection

Base URL: https://app.deck-0.com OpenAPI Spec: GET /api/agents/v1/openapi (no auth required)

Setup

Wallet Source Priority

Use this wallet resolution order when signing API requests or sending transactions:

1. Existing agent wallet provided by the runtime
2. Existing Base wallet provided by the runtime
3. DECK0_PRIVATE_KEY fallback (only when neither wallet above exists)

Fallback setup for step 3:

export DECK0_PRIVATE_KEY="0x..."

Optional fallback chain override (used only for API auth signature verification; contract operations use the chain from the collection/price response and your RPC selection):

export DECK0_CHAIN_ID=8453

Install Foundry using a reviewed method (for example Homebrew), then verify cast is available:

brew install foundry
cast --version

Also uses: curl, jq, shasum (standard on macOS/Linux).

Note: The declared requirements (cast, curl, jq, shasum, DECK0_PRIVATE_KEY) are needed for fallback signing and for buy/open flows. Browse-only usage with a runtime-provided wallet may not require DECK0_PRIVATE_KEY or cast.

The wallet needs native tokens (APE on Apechain, ETH on Base) to buy packs.

Security Notes

• Prefer runtime-provided wallets whenever available.
• DECK0_PRIVATE_KEY is highly sensitive. Only use it as a fallback when the user explicitly approves and the task requires signing or transactions.
• Never print, log, or echo private key values.

Quick Reference

See endpoints.md for complete request/response schemas.

Authentication

All endpoints (except /openapi) require EIP-191 wallet-signed requests via custom headers:

The canonical payload to sign:

deck0-agent-auth-v1
method:{METHOD}
path:{PATH}
query:{SORTED_QUERY}
body_sha256:{SHA256_HEX}
timestamp:{TIMESTAMP}
nonce:{NONCE}
chain_id:{CHAIN_ID}
wallet:{WALLET}

See auth.md for the full signing flow with code examples.

Smart Contracts

Buying and opening packs are on-chain operations:

1. Buy packs: Call GET /api/agents/v1/collections/{address}/price to get a signed price, then call mintPacks() on the album contract with the signature and payment value.
2. Open packs: Call openPacks(packIds) on the album contract to reveal cards, then poll GET /api/agents/v1/me/pack-opening/{txHash}?chainId=... every 5 seconds to get the recap with card details and badges.

Payment formula: value = (packPrice * priceInNative * quantity) / 100

See smart-contracts.md for ABI, payment calculations, and code examples.

Supported Networks

Response Format

All responses follow a standard envelope:

// Success
{ "success": true, "data": { ... }, "share": { "url": "...", "imageUrl": "..." } }

// Error
{ "success": false, "error": { "code": "AGENT_...", "message": "...", "details": { ... } } }

See errors.md for all error codes and troubleshooting.

Sharing URLs

Most responses include URLs that link to the DECK-0 web app. Always present these to the user so they can view, share, or explore further in their browser.

• share.url — Present on most responses. Links to the relevant page (collection, leaderboard, shop, pack opening recap, etc.). Show this to the user as a shareable link.
• share.imageUrl — When available, an image preview URL (e.g., collection cover). Can be used for rich embeds or previews.
• data.cards[].url — On pack opening recap responses, each card includes a direct link to its detail page. Show these to the user so they can view or share individual cards.

Rate Limits

• Per wallet: 60 requests/minute
• Per IP: 120 requests/minute

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After) are included on 429 responses.

Intent Mapping

When the user says:

• "Show me available card collections" → Browse shop albums
• "Tell me about collection 0x..." → Get collection details
• "Buy 3 packs from collection 0x..." → Get signed price, call mintPacks
• "Open my packs" → Call openPacks on contract, then poll pack opening recap
• "What cards did I get?" / "Show my pack opening results" → Get pack opening recap
• "How's my collection progress?" → Get my albums
• "Show my packs" / "What packs do I have?" → List my packs
• "Show my cards" / "What cards do I have?" → List my cards
• "Show the leaderboard" → Get collection leaderboard
• "Share my pack opening" / "Show me the link to my card" → Use share.url or cards[].url from the response
• "I want to create my own card collection" → Submit publisher application

Supporting Files

• auth.md — Full authentication flow, signing code, payload construction
• endpoints.md — Complete API reference with all request/response schemas
• smart-contracts.md — On-chain operations: minting packs, opening packs, ABI, code examples
• examples.md — End-to-end workflow examples with request/response pairs
• errors.md — Error codes, rate limiting, troubleshooting