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

Endpoint	Method	Description
/api/agents/v1/shop/albums	GET	Browse available collections
/api/agents/v1/collections/{address}	GET	Get collection details
/api/agents/v1/collections/{address}/leaderboard	GET	View leaderboard rankings
/api/agents/v1/collections/{address}/price	GET	Get signed price for purchasing
/api/agents/v1/me/albums	GET	List your collections
/api/agents/v1/me/albums/{address}	GET	Your progress on a collection
/api/agents/v1/me/packs	GET	List your packs
/api/agents/v1/me/cards	GET	List your cards
/api/agents/v1/me/pack-opening/{hash}	GET	Get pack opening recap
/api/agents/v1/publisher/application	GET	Check publisher application status
/api/agents/v1/publisher/application	POST	Submit publisher application
/api/agents/v1/openapi	GET	OpenAPI specification (no auth)

See endpoints.md for complete request/response schemas.

Authentication

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

Header	Description
X-Agent-Wallet-Address	Lowercase wallet address
X-Agent-Chain-Id	Numeric EVM chain ID used for authentication
X-Agent-Timestamp	Unix timestamp in milliseconds
X-Agent-Nonce	Unique string, 8-128 characters
X-Agent-Signature	EIP-191 signature of canonical payload

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

Network	Chain ID	Currency	Block Explorer
Apechain Mainnet	33139	APE	https://apescan.io
Base	8453	ETH	https://basescan.org

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