Agent API

Boxes

Buy, open, send and settle mystery boxes.

Four mystery boxes, a normal and a premium one on Base and on Robinhood Chain, share one set of endpoints. Name the box with chain (base or robinhood) and box (normal or premium). Every write answers with a plan, as described in How it works.

Read the boxes

GET /boxes

The four boxes as they stand now.

GET https://www.giftedstock.com/api/agent/v1/boxes
FieldWhat it is
chain, box, addressWhich box and its contract.
priceUsdThe price of one box in dollars.
payWithETH plus USDC on Base or USDG on Robinhood Chain.
ethPriceForOneOne box in ETH right now (null when it cannot be read).
openFeeEthThe opening fee for one box, in ETH.
maxPerTransaction, expiresDaysHow many boxes one call takes and how long a sealed box stays good.
oddsEach prize in dollars with its chance in percent.
bonusPotoneIn (the bonus pot line's odds), prizeUsd, whenShortUsd (paid when the pot cannot cover it) and potUsd. Null for a box with no bonus pot.
payingNowThe stocks that can pay a prize right now.

GET /wallet/{address}

A wallet's balances and mystery boxes on both chains. Balances list ETH and every stock and token the API trades that the wallet holds. A chain that cannot be read right now is null.

{
  "wallet": "0x…",
  "balances": { "base": [{ "token": "ETH", "address": null, "kind": "gas", "amount": "0.002" }, …], "robinhood": […] },
  "sealed": [{ "chain": "base", "box": "normal", "id": "2385", "status": "sealed" }],
  "opening": [],
  "opened": […],
  "complete": true
}

complete: false means some boxes may be missing from this read: read again shortly.

GET /box/{chain}/{box}/{id}

One box: its owner and status (sealed, opening, opened or expired). Once opened, prize names the stock, the amount and its dollar value at opening. While it is opening, batch shows when it was opened, whether its random number is in and from when you may settle it yourself.

Buy

POST /tx/buy

{ "wallet": "0xYou", "skill": "1.3.0", "chain": "base", "box": "normal", "quantity": 5, "payWith": "USDC" }
FieldRule
quantity1 to 200.
payWith"ETH" (if left out), "USDC" on Base or "USDG" on Robinhood Chain.
  • With USDC or USDG: an exact approval when one is needed, then the buy.
  • With ETH: one step that sends 1% over the quote for a price move before the block. The box sends the change back.
  • The new box ids are in the receipt (the box's Transfer events to your wallet) or in GET /wallet/{address}.

Its own refusals: bad_pay, not_on_sale and eth_price_unavailable (pay with the chain's dollar instead).

Open

POST /tx/open

{ "wallet": "0xYou", "skill": "1.3.0", "chain": "base", "box": "normal", "ids": ["2385"] }
  • ids: up to 200 sealed boxes your wallet holds, less than 365 days old.
  • Leave ids out to open every sealed box of that kind the wallet holds, up to 200. summary.ids names them.
  • Opening sends a small fee in ETH with a margin on top. The box sends back what is over the fee.
  • A box goes sealed, then opening, then opened within seconds: the batch settles once its random number is in (Pyth Entropy on Base, drand on Robinhood Chain).

Its own refusals: paused, no_box, not_owner, not_sealed, expired and nothing_to_open (404, when no ids were given and the wallet holds none).

How a prize is drawn and how to check one yourself is on Odds and randomness.

Send

POST /tx/send

{ "wallet": "0xYou", "skill": "1.3.0", "chain": "base", "box": "normal", "ids": ["2385"], "to": "fren.base.eth" }
  • Sealed boxes only, up to 200. They arrive sealed and the receiver opens them.
  • to is an address, a basename or an ENS name. A name resolves to one address for both chains. A contract that cannot hold the boxes is refused.
  • On Robinhood Chain, a to that is a smart wallet on Base with nothing at its address on Robinhood Chain is refused with smart_wallet_elsewhere (409): boxes sent there may never move. Send "confirmRecipient": true only when its owner confirmed they control that address on Robinhood Chain.

Its own refusals: bad_recipient and the open refusals for each id.

Settle a box that stays opening

POST /tx/settle

{ "wallet": "0xYou", "skill": "1.3.0", "chain": "base", "box": "normal", "id": "2385" }

A batch settles within seconds. If it has not after an hour, the wallet that opened the batch may settle it, naming any one box in it. The plan settles the whole batch.

CaseWhat the plan does
An hour after the openSettles the batch: each box's prize comes to your wallet. On Robinhood Chain the plan carries drand's signature for the batch's round, checked by the box's own beacon.
Base, no random number came for 7 daysReturns the boxes to sealed, to be opened again. The open fee is not refunded.
Earliertoo_early (409), with the time you may act.

payout_blocked (409): a stock in the batch cannot be sent right now. We pay it later, but settling it yourself would forfeit those prizes. Send "acceptForfeit": true only if your user accepts losing them. Other refusals: not_opening, not_owner (403) and callback_failed (the random number came but paying failed: we retry it).