Agent API

Gift boxes

Make gift boxes and claim them.

Gift boxes live on Base. Each box holds the same tokens, bought as the gift is made and paid in USDC or ETH. The boxes go to wallets you name or behind a link people claim from. The fee is 2.5% on top: the gift contract's own fee and the app-fee share, both named in summary.fee. The plan format is on How it works. For what a gift box is to people who get one, see What's a gift box?

Read gifts

GET /gifts?wallet={address}

A wallet's gift boxes and the gifts it made.

FieldWhat it is
receivedEach box it holds: its id, gift, state, who sent it and their note. An opened box adds what it held.
createdEach gift it made: direct (with each wallet and whether it opened) or a link (status, boxes left, claimed, taken back, claim times).
pendingTokens an opened box could not send at the time (a paused stock), waiting for withdrawPending on the gift contract.

GET /gift/{batchId}

A link's public facts: open or not, boxes left, who may claim and when, who made it, its note and what each box holds. A gift sent straight to wallets has no link and answers not_a_link.

Make a gift

POST /tx/gift

{
  "wallet": "0xYou",
  "skill": "1.3.0",
  "items": [{ "token": "NVDAc", "usd": "5" }, { "token": "cbBTC", "usd": "1" }],
  "to": ["fren.base.eth", "0xF4E2…96B8"],
  "payWith": "USDC",
  "note": "happy birthday"
}
FieldRule
itemsWhat each box holds: 1 to 20 tokens, each once, by ticker or address. Each takes usd (dollars, at most 2 places) or amount (in the token's units), at least $0.01 of each. Tokenized stocks, tokens such as cbBTC and BNKR, USDC and ETH.
payWith"USDC" or "ETH". The gift router buys each item as the gift is made and sends back what it does not spend.
to1 to 100 wallets, addresses or names (name.base.eth, name.eth), one box each. A contract is refused: a box there could never be opened.
linkInstead of to: a link people claim from (below). Give one of the two.
noteOptional, up to 140 characters, shown with the gift.
designOptional: a design word (0x and 64 hex) or { box, ribbon, title, titleColour, stickers }. Colours as "#9ccc00", a title up to 16 characters, ribbon null for none.
  • The plan is an exact USDC approval when one is needed, then the router's buy. It lasts 20 minutes.
  • A quote more than 3% over what the boxes hold at today's prices is refused with price_moved: build it again shortly.
  • A wallet clearly short of the total is told first with insufficient_balance (409).

Its own refusals: bad_items, unknown_token, below_minimum, bad_pay, bad_to, unknown_name, not_a_wallet, bad_note, bad_design, token_not_allowed, not_buyable, no_quote, no_eth_pool, price_moved and paused.

Open gift boxes

POST /tx/gift/open

{ "wallet": "0xYou", "skill": "1.3.0", "ids": ["624"] }

Up to 200 sealed gift boxes your wallet holds. What each holds goes to your wallet and the box stays as an opened record. Its refusals: no_box, not_holder (403) and not_sealed.