How sorare/api works
Project Type and Purpose
• This project is a collection of code examples and integration scripts that demonstrate how to interact with the Sorare API. The API is based on GraphQL and is used to handle tasks like authentication (including 2FA), managing auctions and offers (bidding, creating, accepting), fetching card details (including MLB/NBA cards), and handling real-time subscription updates via websockets.
• The README shows detailed instructions on using the GraphQL endpoints and the OAuth mechanisms, as well as specialized cases like signing messages with Starkware private keys. Thus, the system is essentially a full-featured client integration toolkit aimed at third-party developers working with Sorare’s blockchain-backed card system.
Analyzing the File Structure
• The top-level files (CHANGELOG.md, README.md) provide project-wide context.
• The “examples” directory holds all the scripts (in JavaScript and Python) which each demonstrate a different aspect of the Sorare API integration:
• Scripts such as acceptSingleSaleOffer.js, bidAuction.js, createSingleSaleOffer.js for managing offers and bids.
• Various subscription examples (subscribeAllCardUpdates.js, subscribeCurrentUserUpdates.js, subscribeTokenWasUpdated.js, etc.) covering realtime updates via websockets.
• GraphQL query mutations are demonstrated in several files (gql_query_all_cards.py, gql_subscription_all_cards.py).
• This modular structure suggests that each file represents a discrete use case (or a service-like component) that interacts with the central Sorare API.
Identifying Main Components
• Client/Developer Application:
• This represents the code examples (the “examples” folder) written in both JavaScript and Python.
• Authentication Module:
• Shows the authentication flow, including password hashing (bcrypt) for initial sign-in, the handling of JWT tokens, and 2FA challenge/response.
• Auction & Offer Management Module:
• Represents the use cases for listing auctions, bidding, creating direct or single sale offers, preparing offers, and accepting offers.
• GraphQL Request Layer:
• How the examples send GraphQL queries and mutations to the API endpoint (https://api.sorare.com/graphql) and include details like headers (Authorization, JWT-AUD, APIKEY, and content-type).
• Subscription / Real-Time Updates Module:
• Shows the use of websockets (wss://ws.sorare.com/cable via ActionCable) for realtime event subscriptions (e.g., watching for card updates, current user changes, auctions, and offers updates).
• External Systems:
• External Ethereum Blockchain / Starkware Rollup: Indicate that actual card ownership and transfer operations are backed by a blockchain network.
• OAuth Endpoints: To cover the “Login with Sorare” flow and token exchanges.
Relationships and Interactions
• Authentication process that connects the Client to the API, including a two-step "signIn" mutation that may trigger a 2FA flow.
• Subscription channel separately: the client establishes a persistent websocket connection to the ActionCable-powered endpoint, receiving real-time updates.
• Clearly label external data flows (like token transfers, approvals) and indicate the various API endpoints (GraphQL HTTP and Websocket).
Architectural Patterns and Technologies
• The system follows a client-driven, API-centric design where the client examples act as “thin” integration layers.
• It uses REST-like HTTP interactions (for fetching schema, signing in, etc.) and GraphQL for all data queries/mutations.
• Real-time updates follow the publish/subscribe pattern via websockets.
• Security practices such as client-side password hashing and private key usage for signing authorization requests.