@ours-protocol/sdk-core
v0.1.0
Published
TypeScript SDK for OURS meme launches and trading on Robinhood and BSC
Readme
@ours-protocol/sdk-core
Launch and trade OURS Memes with ethers v6 on Robinhood mainnet (4663), BSC Testnet (97), and BSC mainnet (56).
Official website: ours.meme
Install
npm install @ours-protocol/sdk-core ethers@^6.15.0Requires Node.js 22+ or a modern browser with fetch, Blob and FormData. The package includes ESM, CommonJS and TypeScript declarations.
Browser wallet
import { BrowserProvider } from "ethers";
import { createClient } from "@ours-protocol/sdk-core";
const provider = new BrowserProvider(window.ethereum);
await provider.send("eth_requestAccounts", []);
const signer = await provider.getSigner();
const client = createClient({
chainId: 97,
runner: signer,
apiEnv: "development",
});The wallet must already be on the selected network. The SDK never changes the wallet network automatically and never accepts a private key in its options.
Node.js wallet
import { JsonRpcProvider, Wallet } from "ethers";
import { createClient } from "@ours-protocol/sdk-core";
const provider = new JsonRpcProvider(process.env.RPC_URL);
const signer = new Wallet(process.env.PRIVATE_KEY!, provider);
const client = createClient({ chainId: 97, runner: signer });Only the caller constructs the Wallet. A Provider-only runner supports reads and transaction building when an explicit account/creator is supplied.
First launch
Choose one of the following logo sources. Both produce a logoUrl string
for the same launch code below.
Option A: an existing image URL
Use an existing HTTPS or IPFS image URL directly. No upload is required.
const logoUrl = "https://example.com/logo.png";
// Or: const logoUrl = "ipfs://<image-cid>";Option B: upload a local image
In Node.js, read your image file and upload its bytes. imageBytes is the
binary file content, not a URL or file name. Here logo.png is an example
image in your own application's working directory.
import { readFile } from "node:fs/promises";
const imageBytes = await readFile("logo.png");
const image = await client.metadata.uploadLogo(
new Blob([new Uint8Array(imageBytes)], { type: "image/png" }),
"logo.png",
);
const logoUrl = image.url;In a browser, use a file selected by the user instead:
<input id="logo" type="file" accept="image/png,image/jpeg,image/gif,image/bmp" />const input = document.querySelector<HTMLInputElement>("#logo");
const file = input?.files?.[0];
if (!file) throw new Error("Select a logo image first");
const image = await client.metadata.uploadLogo(file, file.name);
const logoUrl = image.url;Uploads support JPEG, PNG, GIF and BMP images up to 5 MiB. Match the Blob's MIME type to the actual file format. The backend returns the image URL to put in the token metadata; image bytes are not embedded in the launch transaction.
Launch with the selected logo
import { parseUnits } from "ethers";
await client.auth.login(); // explicit signMessage request, JWT retained in memory
const templates = await client.launch.getTemplates();
console.log(templates); // select an enabled template; IDs are on-chain IDs
const pairAssets = await client.tokens.getPairAssets();
console.log(pairAssets);
const metadata = client.metadata.build({
name: "My Meme",
symbol: "MEME",
logo: logoUrl,
description: "My first OURS Meme",
socials: { website: "https://example.com" },
});
const claim = await client.launch.claimAddress(); // address AND salt from backend
const input = {
chain: "bsc" as const,
metadata,
templateId: 0n, // choose a real enabled template matching your quote asset
claim,
curveFeeBps: 100, // 1%; BSC platform turnover floor is also enforced
platformBps: 10000, // default: all revenue to platform, no project strategies
initialBuyAmount: 0n, // optional atomic first buy, in quote-asset raw units
};
const plan = await client.launch.preview(input);
console.log(plan.steps);
const result = await client.launch.send(input, {
onTransaction: (step, tx) => console.log(step.kind, tx.hash),
});
console.log(claim.address, result.state);No local token-address mining or CREATE2 computation is used. The SDK checks the backend allocation against the configured deployer and an on-chain prediction. Keep the claim for retries after a rejected wallet transaction; do not claim a fresh address unnecessarily.
For an atomic initial buy set initialBuyAmount using the selected quote asset's decimals. Use zero to launch without buying.
Robinhood launch
import { ZeroAddress } from "ethers";
const robinhood = createClient({ chainId: 4663, runner: robinhoodSigner });
await robinhood.auth.login();
const claim = await robinhood.launch.claimAddress();
await robinhood.launch.send({
chain: "robinhood",
metadata,
templateId: 0n,
pairToken: ZeroAddress, // ETH; or an approved ERC20 quote asset
claim,
platformBps: 10000,
initialBuyAmount: 0n,
});Robinhood templates and BSC templates have different structures. The chain-tagged input types prevent mixing them. See the Policies guide in the separate documentation package for project strategy configuration.
Quote and trade on the curve
const token = claim.address;
const quote = await client.trade.quote({
token, side: "buy", amountIn: parseUnits("1", 18),
});
console.log(quote.amountOut, quote.minAmountOut, quote.fee, quote.refund);
// Sends approvals only when needed, then the trade.
await client.trade.buy({ token, amountIn: parseUnits("1", 18) });
await client.trade.sell({ token, amountIn: parseUnits("100", 18) });Buying spends the quote asset; selling spends Meme. All input amounts are bigint raw units. Query decimals rather than assuming all quote assets use 18 decimals. Quotes include current curve taxes. The last buy may spend less than requested; the unused amount is refunded. The encoded price bound is adjusted for partial fills using the same integer rules as the contract.
Trade after migration
const state = await client.tokens.getState(token);
if (state.phase === "migrated") {
const quote = await client.swap.quote({
token, side: "buy", amountIn: parseUnits("1", 18),
});
console.log(quote.amountOut, quote.minAmountOut);
await client.swap.send({ token, side: "buy", amountIn: parseUnits("1", 18) });
await client.swap.send({ token, side: "sell", amountIn: parseUnits("100", 18) });
}Only the official Meme/quote graduation pool is supported in v0.1. Native ETH/BNB is selected automatically for native-quote projects. External quote amountOut is already net of pool/Hook fees; fee=0 means a separate fee breakdown is not supplied by the external Quoter, not that the trade is fee-free.
A completed curve can be awaiting migration. The SDK never treats that state as an external pool ready to trade, and does not silently call a migration method.
Build without sending
const plan = await client.trade.build({
token, side: "buy", amountIn: parseUnits("1", 18),
account: walletAddress, // required for a Provider-only client
});
for (const step of plan.steps) {
console.log(step.kind, step.to, step.data, step.value);
// Your app may send each step and wait before proceeding.
}
// Or explicitly hand the plan to a signer-backed client:
await client.transactions.send(plan);Build/preview methods do not sign, approve, broadcast or claim a new address. Approval steps are dependent transactions, not one atomic transaction. A failure stops subsequent steps; previously confirmed approvals remain on-chain. Each business transaction reverts atomically if its own execution fails.
Configuration
const client = createClient({
chainId: 97,
runner: signer, // Provider | Signer; Signer must have a Provider
wsProvider, // optional caller-owned WebSocketProvider
apiEnv: "development", // "production" | "development"
apiBaseUrl: "https://api.ours.meme/api", // optional full prefix override
accessToken: () => myCurrentJwt,
approvalMode: "max", // default; use "exact" for minimum required ERC20 approval
slippageBps: 100,
deadlineSeconds: 300,
permit2ExpirationSeconds: 30 * 86400,
migrationGasBuffer: 3_000_000n, // BSC buy/launch automatic-migration headroom
// maxGasLimit: 16_000_000n, // optional lower ceiling for your RPC/wallet
});Defaults: chain 97 uses the development API; 4663 and 56 use production. API selection is independent of RPC selection. JWTs, quotes, balances, permissions and prices are not persisted in browser storage by the SDK.
BSC mainnet OURS contracts are not deployed yet. Supply deployment addresses after deployment; calling launch/trade without them fails clearly. Detailed network references are available in the separate documentation package.
Documentation
Full SDK methods, strategy policies, network references, contract methods and HTML API documentation are published separately as @ours-protocol/sdk-docs.
npm install --save-dev @ours-protocol/sdk-docsOpen api/index.html from the installed documentation package in a browser,
or read its Markdown guides and TypeScript examples. The runtime SDK does not
include the documentation package or depend on it.
Complete ABIs remain available from the SDK root export or from
@ours-protocol/sdk-core/abi/<chain>/<Contract>.json. Revenue contracts are available
as low-level ethers Contracts and retain all on-chain access restrictions.
BSC sends automatically respect the 16,777,216 transaction gas ceiling. Extra Gas headroom is reduced when necessary; estimates above the cap fail before broadcast. Full ABI JSON files are compacted without removing ABI entries.
