Components
Request Flow
When you make a call — whether through an SDK or a direct REST request — here’s what happens under the hood:1
SDK call or REST request
Your application initiates a request by calling an SDK method or hitting a REST endpoint with a wallet address.
2
RPC provider connects to blockchain
The SDK (or the REST API’s backend) connects to the blockchain via an RPC provider to query on-chain state.
3
Smart contract reads/writes state
The relevant smart contract is queried (or written to), returning or updating credit data, loan records, and SBT metadata.
4
Response returned to caller
The result is decoded and returned to your application — either as a typed SDK response object or a structured JSON body from the REST API.
SDK vs REST API
Both integration paths expose the same underlying credit data, but they operate differently: SDK — The JavaScript and Python SDKs read directly from the blockchain via an RPC provider. This gives you the freshest possible data with no intermediary caching layer. Choose the SDK when you need real-time state, are building server-side services with direct chain access, or want strongly typed contract interactions. REST API — The REST API sits in front of the blockchain and serves cached, optimized responses over standard HTTP. You don’t need to manage an RPC provider, handle ABIs, or parse raw contract output. Choose the REST API when you want the simplest integration, are building frontend applications, or need to minimize latency for read-heavy workloads.BlackSwan currently supports two testnets: Polygon Amoy and Ethereum Sepolia. All SDK methods and REST endpoints work identically on both networks. Mainnet support is planned for v1.1 — see the Roadmap for details.