Start here
Quickstart
Buy and open a box from code in a few minutes.
This buys one normal mystery box on Base with USDC and opens it, from a short Node script. The API answers each request with the transactions to send; the script signs them with your key. The key never leaves your machine.
Before you start
- Node 20 or later.
- A test wallet's private key, holding a little ETH on Base for gas and a little USDC.
- No API key: the agent API is open.
Buy and open a box
Step 1: See the boxes
GET https://www.giftedstock.com/api/agent/v1/boxes shows each box's price, odds and opening fee right now.
curl https://www.giftedstock.com/api/agent/v1/boxesStep 2: Install viem
In an empty folder, install viem to sign and send.
npm init -y && npm pkg set type=module && npm i viemStep 3: Save the script
Save this as box.mjs. It asks for a buy plan, sends it, then asks for an open plan and sends that.
import { createPublicClient, createWalletClient, http } from "viem"; import { privateKeyToAccount } from "viem/accounts"; import { base } from "viem/chains"; const API = "https://www.giftedstock.com/api/agent/v1"; const account = privateKeyToAccount(process.env.PRIVATE_KEY); const wallet = createWalletClient({ account, chain: base, transport: http() }); const pub = createPublicClient({ chain: base, transport: http() }); // ask for a plan: the unsigned transactions that do what the body asks async function plan(path, body) { const res = await fetch(`${API}/${path}`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ wallet: account.address, skill: "1.3.0", ...body }), }); const json = await res.json(); if (!res.ok) throw new Error(`${json.error}: ${json.message}`); return json; } // send each step in order, each once the one before is mined async function send(p) { for (const s of p.steps) { if (s.chainId !== 8453) throw new Error("not a Base step"); const hash = await wallet.sendTransaction({ to: s.to, data: s.data, value: BigInt(s.value) }); const receipt = await pub.waitForTransactionReceipt({ hash }); if (receipt.status !== "success") throw new Error(`failed: ${s.description}`); console.log("done:", s.description); } } const buy = await plan("tx/buy", { chain: "base", box: "normal", quantity: 1, payWith: "USDC" }); console.log(buy.summary); await send(buy); // no ids: open every sealed normal box this wallet holds on Base const open = await plan("tx/open", { chain: "base", box: "normal" }); await send(open); console.log("opening:", open.summary.ids);Step 4: Run it
The buy is an exact USDC approval, then the buy. The open is one step that sends a small fee in ETH.
PRIVATE_KEY=0x… node box.mjsStep 5: Read your prize
The opening settles within seconds. Read the box with the id the script printed.
curl https://www.giftedstock.com/api/agent/v1/box/base/normal/<id>
Once status is opened, prize names the stock, the amount and its dollar value. The stock is already in your wallet.
Next steps
- Every endpoint for boxes, including send and settle: Boxes.
- Gifts to frens or behind a link: Gift boxes.
- Trades and bridges: Swap and bridge.
- Hand it all to an AI agent: SKILL.md.
- A ready script that checks, dry-runs and asks before sending:
examples/giftedstock.mjsin the skill repo ↗.