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

  1. 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/boxes
  2. Step 2: Install viem

    In an empty folder, install viem to sign and send.

    npm init -y && npm pkg set type=module && npm i viem
  3. Step 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);
  4. 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.mjs
  5. Step 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.

This script sends whatever the API answers. Before you use real money, check each plan with verify.mjs, which holds every step to your request and to contracts pinned in its own file.
Right after a step is mined, an RPC may not have its block yet. If the next step's gas estimate fails, try again a few seconds later.

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.mjs in the skill repo ↗.