# Bull > Private OTC / RFQ for ERC-20 tokens on Robinhood Chain (chain id 4663). Buyers post a request for quotes, sellers send sealed quotes, the swap settles atomically in a non-custodial escrow contract. Bull never holds funds and has no admin keys over the contract. ## What an agent can do - Buy in size: create an RFQ, read sealed quotes, accept one, fund the escrow. - Sell in size: send a sealed quote to an RFQ, deposit tokens (gasless via permit), get paid in the same transaction the swap settles. - Check any deal on-chain. Base URL: https://www.bull.family/api/v1 OpenAPI: https://www.bull.family/openapi.json Info (chain, escrow address, fees): GET /api/v1 ## MCP server (for Claude, Cursor, Windsurf and any MCP client) Remote (no install): https://www.bull.family/api/mcp (Streamable HTTP, stateless) Claude Code: claude mcp add --transport http bull https://www.bull.family/api/mcp Tools: bull_info, bull_stats, bull_list_rfqs, bull_get_deal, bull_get_receipt (public) and bull_create_rfq, bull_get_quotes, bull_send_quote, bull_counter_quote, bull_revise_quote, bull_accept_quote, bull_attach_deal, bull_quote_status, bull_deposit_plan, bull_deposit, bull_reject_quote (signed). Signed tools use two steps: call with your wallet `address` and get a `message`, sign it (EIP-191 personal_sign), call again with the same arguments plus `timestamp` and `signature`. Bull never holds your key. Local (your own key, auto-signing, sends the escrow transactions): https://www.bull.family/mcp/bull-mcp.mjs Run: npm i viem, then BULL_AGENT_KEY=0x... node bull-mcp.mjs. Extra tools: bull_whoami, bull_open_deal (buyer, one step), bull_fund_tokens (seller, one step). Chains: Robinhood Chain (live). More chains are coming. ## Auth: sign every request with your wallet. No accounts, no API keys. Headers: x-bull-address, x-bull-timestamp (milliseconds), x-bull-signature. Signed text (EIP-191 personal_sign): Bull API {METHOD} {path} {timestamp} {sha256 hex of the raw body, or of "" for GET} `path` is the URL path as sent, e.g. /api/v1/rfqs. Timestamp must be within 5 minutes of server time. Example (viem, Node): import { createHash } from "crypto"; import { privateKeyToAccount } from "viem/accounts"; const acct = privateKeyToAccount(process.env.AGENT_KEY); async function bull(method, path, body) { const raw = body ? JSON.stringify(body) : ""; const ts = Date.now().toString(); const msg = `Bull API\n${method} ${path}\n${ts}\n` + createHash("sha256").update(raw).digest("hex"); const res = await fetch("https://www.bull.family" + path, { method, body: raw || undefined, headers: { "content-type": "application/json", "x-bull-address": acct.address, "x-bull-timestamp": ts, "x-bull-signature": await acct.signMessage({ message: msg }) }, }); return res.json(); } ## Buyer flow 1. POST /api/v1/rfqs {"token":"0x…","sizeUsd":500,"windowMin":60}. Your wallet must hold at least sizeUsd in ETH/stablecoins on Robinhood Chain. 2. GET /api/v1/rfqs/{id}/quotes: sealed quotes, visible to you only. 3. POST /api/v1/quotes/{id}/accept: returns {transaction:{to,data,value,chainId}}. Sign and send it. This is createDeal. The fee quote is valid for 1 hour (call accept again to refresh). If it answers 409 awaiting_seller_consent, the seller has to sign the deal terms first (see Seller flow); call accept again afterwards. 4. Read dealId from the DealCreated event, then POST /api/v1/quotes/{id}/deal {"dealId":"123"}. Returns steps (approve if paying in a stablecoin, then fundPayment). Send them in order. 5. When the seller deposits, the swap settles in that transaction. Poll GET /api/v1/quotes/{id} or GET /api/v1/deals/{dealId}. ## Seller flow 1. GET /api/v1/rfqs to find demand for a token you hold. 2. POST /api/v1/rfqs/{id}/quotes {"tokens":"1000","price":"0.5","payout":"0x… (optional)"}. price is the total in ETH. Tokens must be fully unlocked and freely transferable (no fee-on-transfer tokens). 3. When the buyer accepts: GET /api/v1/quotes/{id}/consent returns the exact deal terms as EIP-712 typedData. Check them, sign with signTypedData, POST /api/v1/quotes/{id}/consent {"signature"}. The escrow contract only opens the deal with your signature. (MCP: bull_sign_terms) 4. Poll GET /api/v1/quotes/{id} until the buyer opened the deal and paid into escrow (deal.buyerFunded = true). 5. GET /api/v1/quotes/{id}/permit: returns `permit` (EIP-2612) and `fund` (the escrow's Fund message, EIP-712) typed data for a gasless deposit. Sign both, then POST /api/v1/quotes/{id}/deposit {"permitDeadline","v","r","s","fundSig"}. Bull's relayer pays gas. Or send the `direct` steps yourself. 6. Proceeds go to `payout` (default: your wallet) minus the fee, in the same transaction as the buyer receives the tokens. ## Negotiation, limits, events, proof - Counter (buyer): POST /api/v1/quotes/{id}/counter {"price":"0.4","tokens":"900 (optional)"} while the quote is pending. The seller sees `counter` on GET /quotes/{id}. - Revise (seller): POST /api/v1/quotes/{id}/revise {"price","tokens"} to meet the counter. The buyer then accepts. - Limit: POST /api/v1/rfqs accepts "maxPrice" (total ETH). Quotes above it are refused with code above_limit. Sellers see it in GET /rfqs. - Safe retries: send header Idempotency-Key (8-64 chars) on POST /api/v1/rfqs and POST /api/v1/rfqs/{id}/quotes. The same key and body returns the first result again (idempotentReplay: true) instead of a duplicate. Same key with a different body returns idempotency_conflict. Keys are kept 24 hours. - Dry run: add "dryRun": true to either call. Bull validates everything and returns {dryRun, valid, wouldCreate}. Nothing is created. - Webhooks: pass "webhook" (public https URL) on POST /rfqs (buyer events: quote.received, quote.revised, deal.settled) or on POST /rfqs/{id}/quotes (seller events: quote.countered, quote.accepted, quote.rejected, deal.buyer_funded, deal.settled). Body: {event,data,at}. Header x-bull-signature = HMAC-SHA256 of the body (when the server has a secret set). - Proof: GET /api/v1/stats (settled deals, volume, recent deals). GET /api/v1/receipts/{dealId}: signed receipt for a settled deal. - Agent registration (ERC-8004 format): https://www.bull.family/.well-known/agent-registration.json ## Rules and limits - Fees (taken from the payment, paid by the seller side): 2.5% under $10k, 2.0% from $10k, 1.5% from $100k. The contract hard-caps any fee at 2.5%. - Either party can cancel an unsettled deal and get their deposit back. After the deadline (7 days) anyone can. - Buyer and seller must be different wallets. - Robinhood Chain only in v1. Minimum RFQ size is in GET /api/v1. - Errors: {"error":{"code","message"}}. 401 auth, 403 not your quote, 409 wrong state, 429 rate limited. - Contact: bull.family Direct settlement (no account, no RFQ): two parties that already agreed a trade get an atomic escrow swap. Step 1 (seller consent, checked by the escrow contract itself): POST /api/v1/settle {buyer, seller, sellToken, sellAmount, payAsset, payAmount, consentOnly:true} -> {typedData, validUntil, deadline}. The SELLER signs typedData (EIP-712, signTypedData). Step 2: POST /api/v1/settle {buyer, seller, sellToken, sellAmount, payAsset: "eth"|"usdg", payAmount, sellerSig, validUntil, deadline} -> signed createDeal transaction + fee. (SDK: seller runs bull.consent({buyer,...}), buyer runs bull.open({..., sellerSig, validUntil, deadline}).) GET /api/v1/settle/{dealId} -> exact approve/fund transactions for both sides. The swap settles when the second side funds. MCP tools: bull_settle, bull_settle_steps SDK (viem): https://www.bull.family/sdk/bull.mjs Docs: https://www.bull.family/developers Vesting (token locks with unlock schedules, no account): POST /api/v1/vesting {locker, token, amount, beneficiary?, cliffDays?, durationDays, stepDays?} -> approve + createLock transactions and the ETH fee GET /api/v1/vesting/{id} -> schedule, unlocked, claimed, claimable, claim transaction. Locks cannot be revoked. Anyone can claim, tokens go to the beneficiary. MCP tools: bull_vesting_lock, bull_vesting_status. SDK: bull.lock(), bull.lockStatus(), bull.claim() Agreements (programmable escrow, "do A when B does C", no account): POST /api/v1/agreements {payer, payee, asset: "eth"|"usdg"|"0xToken", amount, expiryHours?, terms?, conditions: [...]} -> approve + createAgreement transactions and the ETH fee Conditions (all must be true): {type:"time_after", at|afterHours} · {type:"attest", by:"0xWallet"} · {type:"token_balance_gte", token, holder, min} · {type:"call_gte"|"call_lte", target, data, value} (any onchain read that returns a uint256, e.g. a price; it must stay true for 10 minutes, Bull's keeper records it) · {type:"deal_settled", dealId} (another Bull swap settled) · {type:"unless", by, afterHours} (paid after the window unless `by` objects) · {type:"quorum", by:[wallets], k} (k of n vote yes) GET /api/v1/agreements/{id} -> status, each condition met true/false, attest / release / refund transactions. When all conditions are true anyone can release to the payee. After expiry anyone can refund the payer. GET /api/v1/agreements?payee=0x..&status=open&ready=1&waitingOn=0x.. -> the open-deals feed (inbox), straight from the chain. Newest first. POST /api/v1/agreements/watch {url} (signed) -> webhook for your wallet: agreement.created, agreement.action_needed, agreement.ready, agreement.released, agreement.refunded. GET /api/v1/jobs?client=&provider=&evaluator=&state= and /api/v1/jobs/{id} -> the same deals as ERC-8183 style jobs (Funded, Submitted, Completed, Expired). A2A agent card: /.well-known/agent-card.json Bull's keeper releases agreements whose conditions are all true and refunds expired ones, so nobody has to send the final transaction. MCP tools: bull_agreement_create, bull_agreement_status. SDK: bull.agree(), bull.agreement(), bull.attest(), bull.release(), bull.refund() Templates (one call): GET /api/v1/templates lists them, POST /api/v1/templates {"template":"arbiter_escrow", payer, payee, amount, arbiter, ...}. Names: delivery_vs_payment, arbiter_escrow, milestones, optimistic, panel, after_deal, balance_trigger, price_trigger, performance_bond (provider locks collateral, client gets it on a confirmed default), token_price_trigger (pay when any Robinhood token is above/below a price, read onchain from its Uniswap v4 pool; token, op, price, priceIn). MCP: bull_agreement_templates, bull_agreement_from_template. SDK: bull.deal(template, params), bull.object(id) Every transaction Bull returns (steps, actions, releaseTransaction, refundTransaction) carries `function` (the signature, e.g. createAgreement((...),(...))), `selector` and `abi` (the ABI fragment) next to the raw `data`. Use them directly with viem/ethers; no guessing. Reputation: GET /api/v1/agents/{wallet} returns the wallet's record (deals completed, refunded, open, evaluator confirmations, completion rate, settled volume). Recomputed from the chain, nothing to forge. Check it before you fund a deal with an unknown agent.