Developers · Robinhood Chain testnet 46630

Build on BLACKOUT

Private RFQ, atomic escrow settlement, a shielded vault and on-chain proofs, exposed as a REST API, a TypeScript SDK and an MCP server for agents. These are the same primitives this app runs on.

01

Overview

The server never holds your key. Every write comes back either as an EIP-712 message you sign, or as an unsigned transaction you send from your own wallet.

Trade terms stay private. Size, limit price and quotes travel as X25519 + XChaCha20 ciphertext addressed to the parties. The relay, webhooks and receipts carry ids, hashes and statuses only.

Settlement is atomic. Both sides deposit into BilateralEscrow and it swaps in one transaction, or each side takes its deposit back after the deadline.

REST

/api/v1

Plain HTTP + JSON. Works from any language.

SDK

@blackout/sdk

TypeScript. Handles signing, encryption and simulation for you.

MCP

@blackout/mcp

Tools for AI agents, bounded by a signed policy.

02

How a trade works

  1. STEP 1

    Publish a key

    Each party signs once to derive an X25519 coordination key and registers the public half (POST /keys).

  2. STEP 2

    Open an RFQ

    The taker encrypts size and limit to each invited maker (POST /rfqs). The relay stores ciphertext only.

  3. STEP 3

    Quote and accept

    Makers reply with encrypted quotes; the taker decrypts locally and accepts one (POST /quotes/:id/accept).

  4. STEP 4

    Fund the escrow

    Both sides get an unsigned tx from POST /settlements/:id/fund and send it from their own wallet.

  5. STEP 5

    Settle atomically

    When both deposits are in, BilateralEscrow swaps them in one tx. Before the deadline neither side can be short-changed; after it, either can refund.

  6. STEP 6

    Prove it

    A public receipt (GET /receipts/:id) shows that it settled, without revealing size or price.

03

Quickstart

Base URL https://blackoutweb-production.up.railway.app/api/v1. Pass ?chainId=46630; it is the only chain served, other ids return UNSUPPORTED_CHAIN.

The Stock Token list mirrors the mainnet (4663) registry, so /markets on 46630 returns [] until testnet tokens are listed. Testnet trades use token addresses directly.

HOST=https://blackoutweb-production.up.railway.app

# open endpoints, no key needed
curl "$HOST/api/v1/markets?chainId=46630"
curl "$HOST/api/v1/settlements/0x<id>?chainId=46630"
curl "$HOST/api/v1/receipts/0x<id>?chainId=46630"

# errors always look like
# {"error":{"code":"UNSUPPORTED_CHAIN","message":"..."}}

04

REST API

Auth column: open needs nothing; EIP-712 body means the body is a typed message signed by your wallet; signed read means you sign to prove you are a party; x-api-key needs an API key. Paths are relative to /api/v1.

Markets

Stock Token registry. Read-only, no signature.

GET/marketsopenAll markets on the chain.
GET/markets/:symbolOrAddressopenOne market. Prefer the token address.A symbol shared by two tokens returns 409 AMBIGUOUS_SYMBOL.

Coordination keys

Each party publishes an X25519 public key once, so others can encrypt RFQs and quotes to it.

POST/keysEIP-712 bodyRegister your coordination public key (KeyRequest).
GET/keys/:owneropenLook up someone's public key.

Private RFQ

Size, limit price and quotes travel only as ciphertext. The relay sees who talks to whom, not what.

POST/rfqsEIP-712 bodyOpen an RFQ encrypted to the invited makers.
GET/rfqssigned readYour inbox: RFQs you opened or were invited to.
GET/rfqs/:idsigned readOne RFQ. Not a party -> 404.
POST/rfqs/:id/quotesEIP-712 bodySubmit an encrypted quote.quote.rfqId must match the path.
POST/quotes/:id/acceptEIP-712 bodyAccept a quote (RFQ maker only).
POST/rfqs/:id/cancelEIP-712 bodyCancel your RFQ.
POST/rfqs/:id/settlementEIP-712 bodyLink the escrow settlement id to the RFQ.

Settlement

Writes return an UNSIGNED transaction (PreparedTx) plus any ERC-20 approval. You sign and send.

GET/settlements/:idopenDeal state from BilateralEscrow: OPEN, PARTIALLY_FUNDED or CLOSED.
POST/settlements/:id/fund{ from, terms }Prepare the funding tx for your side.terms must hash to the deal id, otherwise 409 TERMS_MISMATCH.
POST/settlements/:id/refund{ from, terms }Prepare a refund.Only after the deadline (NOT_EXPIRED before).

Receipts

Public proof that a deal settled. Contains ids, hashes and proof types, never size or price.

GET/receipts/:idopenReceipt for a settled id.Not settled -> 404 immediately. Add &block=<n> to skip the log scan.

Agents

Delegated trading through an AgentAccount with an owner-signed policy.

GET/agents/:agent/policy?account=&token=openOn-chain session state and remaining per-call / daily limits.
POST/agents/:agent/simulateEIP-712 bodyDry-run the full policy pipeline. Nothing executes.

Webhooks

Need an API key (the key owns the subscription).

POST/webhooksx-api-keySubscribe { url, events[] }. The secret is returned only in this response.
GET/webhooksx-api-keyYour subscriptions, without secrets.
DELETE/webhooks/:idx-api-keyRemove a subscription.
GET/webhooks/:id/deliveriesx-api-keyLast 100 deliveries: status, attempts, lastError.
POST/webhooks/:id/testx-api-keySend a webhook.test event now.

Full request and response shapes: docs/API_SPEC.md in the repository.

05

Errors

Every error is { "error": { "code", "message" } }. Branch on code, show message.

400BAD_REQUESTBody or parameter failed validation.
400UNSUPPORTED_CHAINchainId is not served. Use 46630.
401UNAUTHENTICATEDSigned read missing or invalid.
401API_KEY_REQUIREDThis deployment requires x-api-key on writes.
401BAD_API_KEYUnknown API key.
404NOT_FOUNDNo such object, or you are not a party to it.
409TERMS_MISMATCHThe terms you sent do not hash to this settlement id.
409ALREADY_FUNDEDYour side of the escrow is already funded.
409AMBIGUOUS_SYMBOLTwo tokens share the symbol. Use the address.
409PAST_DEADLINEToo late to fund.
409NOT_EXPIREDToo early to refund.
413TOO_LARGEBody over 256 KiB.
422IDEMPOTENCY_CONFLICTSame Idempotency-Key, different body.
422RELAY_REJECTEDThe coordination relay refused the signed request (see message).
429RATE_LIMITEDOver 120 req/min per key, or 30 per IP without one.

06

SDK · @blackout/sdk

One client, grouped by area. Nothing moves money unless you call settlement.execute with confirm: true; it checks the wallet and chain and simulates first.

import { Blackout } from "@blackout/sdk";
import { deriveCoordinationKey } from "@blackout/private-rfq";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const bo = new Blackout({
  baseUrl: "https://blackoutweb-production.up.railway.app", // origin only, the SDK adds /api/v1
  chainId: 46630,
  signer: account,                                              // signs EIP-712 coordination requests
  coordinationKey: await deriveCoordinationKey(account, 46630), // X25519 key derived from one signature
  walletClient: createWalletClient({ account, transport: http(RPC) }),
  publicClient: createPublicClient({ transport: http(RPC) }),
});

await bo.keys.register();                                       // once per wallet

const { rfqId } = await bo.rfq.open({
  market: TOKEN, side: "BUY", size: 10n * 10n ** 18n,
  limitPayAmount: 2_000n * 10n ** 6n, settlementAsset: USDG,
  ttlSeconds: 600, invitees: [MAKER],                           // encrypted to MAKER's published key
});

const [best] = await bo.rfq.getQuotes(rfqId);                   // decrypted locally
await bo.rfq.accept(rfqId, best);

const tx = await bo.settlement.prepareFund(settlementId, best.body.terms); // unsigned + approval
await bo.settlement.execute(tx, { confirm: true });                       // simulate, then send

bo.markets

  • list()All markets on the chain.
  • get(symbolOrAddress)One market.

bo.keys

  • register()Publish your coordination public key.needs: signer, coordinationKey
  • get(owner)Someone's public key.

bo.rfq

  • open({ ...terms, invitees }, idemKey?)Encrypt the RFQ to each invitee and post it.needs: signer, coordinationKey
  • inbox()RFQs you opened or were invited to (signed read).needs: signer
  • get(id)One RFQ (signed read).needs: signer
  • openInvitation(id)Decrypt an RFQ you were invited to.needs: coordinationKey
  • quote(id, payAmount, { settleBy, validFor? })Encrypt and submit a quote.needs: signer, coordinationKey
  • getQuotes(id)Decrypt the quotes on your RFQ.needs: coordinationKey
  • accept(id, quote)Accept one quote.needs: signer
  • cancel(id)Cancel your RFQ.needs: signer
  • linkSettlement(id, settlementId)Attach the escrow id.needs: signer

bo.settlement

  • get(id)Deal state.
  • prepareFund(id, terms, from?)Unsigned funding tx + approval.
  • prepareRefund(id, terms, from?)Unsigned refund tx.
  • execute(tx, { confirm: true, dryRun? })Checks wallet and chain, simulates, sends the approval only if allowance is short, then sends. Refuses without confirm: true.needs: walletClient, publicClient

bo.receipts

  • get(settlementId)Public receipt.

bo.webhooks

  • create(url, events)Subscribe. Store the returned secret.needs: apiKey
  • list() / remove(id)Manage subscriptions.needs: apiKey
  • deliveries(id) / test(id)Debug deliveries.needs: apiKey

bo.agents

  • policy(agent, account, token?)Session state and remaining limits.
  • simulate({ policy, request })Dry-run a request against the signed policy.

07

Proofs & receipts · @blackout/proofs

A settlement can be gated on proofs (funding, eligibility, price limit, agent authorization). ProofCondition lets it finalize only when ProofRegistry holds a valid record bound to that settlement.

Proof type ids are keccak256("blackout.proof.<name>.v<n>"). See live status in the Proof Center. Receipts (GET /receipts/:id) return 404 quickly for ids that have not settled.

import { checkProof, proofTypeId } from "@blackout/proofs";

const r = await checkProof(
  publicClient,
  "0xAff2139C8BE891025189bC560fc7F40A4CeF43Dc", // ProofRegistry on 46630
  proofTypeId("FUNDING"),                       // keccak256("blackout.proof.funding.v2")
  [publicInput0, publicInput1],                 // bytes32[] public inputs
);

// Same order as ProofRegistry.isValid:
// r.status: "NOT_RECORDED" | "REVOKED" | "EXPIRED" | "TYPE_INACTIVE" | "VALID"
// r.valid is true exactly when the registry says the proof is valid

08

Agents & MCP · @blackout/mcp

An agent trades through an AgentAccount using a session key that holds gas only. Every write tool runs schema validation, your signed policy, a simulation and a risk summary before acting, and accepts dryRun and idempotencyKey. Create the policy in the Agent Control Center.

{
  "mcpServers": {
    "blackout": {
      "command": "pnpm",
      "args": ["--filter", "@blackout/mcp", "start"],
      "env": {
        "BLACKOUT_API_URL": "https://blackoutweb-production.up.railway.app/api/v1",
        "BLACKOUT_RPC_URL": "https://rpc.testnet.chain.robinhood.com",
        "BLACKOUT_AGENT_KEY": "<session key, holds gas only>",
        "BLACKOUT_ACCOUNT": "<your AgentAccount>",
        "BLACKOUT_POLICY": "./agent-policy.json"
      }
    }
  }
}
blackout_get_marketsreadList markets.
blackout_get_marketreadOne market by address or symbol.
blackout_list_rfqsreadThe agent's RFQ inbox.
blackout_get_rfq_statusreadStatus of one RFQ.
blackout_get_quotesreadDecrypted quotes on the agent's RFQ.
blackout_get_receiptreadPublic receipt.
blackout_get_agent_policyreadPolicy and remaining limits.
blackout_simulate_actionreadRun the policy pipeline without acting.
blackout_create_rfqwriteOpen an encrypted RFQ.
blackout_submit_quotewriteQuote on an RFQ (dry-run only in v1).
blackout_accept_quotewriteAccept a quote.
blackout_fund_settlementwriteApprove + fund the agent's side via the session key.
blackout_refundwriteRefund after the deadline.

09

Webhooks

POST /api/v1/webhooks { url, events } with your API key returns a signing secret once. Deliveries carry ids and statuses only, never sizes, prices or terms. Failed deliveries retry after 10 s, 1 min, 5 min and 30 min with the same event id.

intent.createdintent.expiredquote.receivedquote.counteredquote.acceptedproof.requiredproof.verifiedsettlement.fundedsettlement.readysettlement.finalizedsettlement.refundedpolicy.deniedsession.grantedsession.revokedsession.executedshielded.commitmentshielded.nullifiergovernance.scheduledgovernance.executedgovernance.cancelled
import { verifyWebhook } from "@blackout/sdk";

export async function POST(req: Request) {
  const body = await req.text();                       // raw body, before JSON.parse
  const ok = verifyWebhook({
    secret: process.env.BLACKOUT_WEBHOOK_SECRET!,
    id: req.headers.get("blackout-webhook-id")!,
    signature: req.headers.get("blackout-signature")!,  // t=<unix>,v1=<hmac-sha256 hex>
    body,
  });
  if (!ok) return new Response("bad signature", { status: 401 });
  const event = JSON.parse(body);                      // dedupe on event.id: retries reuse it
  return new Response(null, { status: 204 });
}

10

Contracts on 46630

Read from the deployment files on each request, so this is the exact set the app uses.

Settlement

AgreementEngine0xaD3dCC5769A1955220C746A9f33e3C70699bA6A3Multi-condition agreements (not exposed to agents in v1).
AttestationCondition0xD16638a719B3F96EAB761f0539Adb8D11f8c48C3Condition: an attester signed off.
BilateralEscrow0x693cF64F1215625e24d4a916b2C73a0C7d3599ABTwo-sided atomic swap: both deposit and it settles in one tx, or each refunds after the deadline.
CompositeCondition0x17DFeaCDB915193820D58A8dBaf22B0D1D8A6f22AND / OR of other conditions.
DeadlineCondition0x79577921150c42aa90fb2d60BCb971A74a6C027cCondition: before a timestamp.
SettlementCondition0x6EAaA78b17dEdb63c1110F68a222B46b7a87A3DBCondition: another settlement closed.
SettlementFactory0x3e91b773FD8Bc2aAba93DB35Ecdd8472B72F0d6eDeploys settlement instances.
SettlementRegistry0xEA05C7da1E6332cD366dD40322bfF642c20B204fRecords which ids settled (receipts read it).
TimeCondition0x739924f8dAC1173f2B20C634De1AFD69c1346e50Condition: after a timestamp.
owner0x8EB93b38B5eFB2eBDa9644580C8682bE00f67c9EOwner recorded at deploy time.

Shielded vault & proofs

AuthorizationVerifier0xfEc27E9EBaDdF14A70b63685EFF802403040e9F6Verifier for AGENT_AUTHORIZATION proofs.
EligibilityVerifier0xCA1d74e3a0a46E72335c5A643f0085F869C0ceb9Verifier for ELIGIBILITY proofs.
FundingCondition0xB21ca2b5f8670Fc9062a9c1390A76A160f719D37Condition: FUNDING proof present.
FundingVerifier0x8a1755525af48cF7eD9b1f9D511ce697DA0FCBD3Verifier for FUNDING proofs.
HonkVerifier0xEb9e33356F9fC4B1DBFFCC2E8be0ec74E922Ec29Generated UltraHonk verifier for the transact circuit.
PriceLimitCondition0xdb2FeeC98049C4d8a9D463CAEe3df1472cE86ED4Condition: PRICE_LIMIT proof present.
PriceLimitVerifier0xfee4ca6935977187B2C379e4396011DaE6f60E42Verifier for PRICE_LIMIT proofs.
ProofCondition0x9cC3574c6a8C75f4B15026B8Cb28d39eE7Db2fefCondition: a valid proof of a given type exists for this settlement.
ProofRegistry0xAff2139C8BE891025189bC560fc7F40A4CeF43DcStores proof records; isValid checks recorded / revoked / expired / type active.
ShieldedVault0x3C748fF0d5680e7C5E4C1774F866A26DCfb291cfShielded pool: deposit, private transfer, withdraw with a ZK proof. Per-asset deposit cap.
owner0x8EB93b38B5eFB2eBDa9644580C8682bE00f67c9EOwner recorded at deploy time.
testToken0x0000000000000000000000000000000000000000Test ERC-20 used for vault demos.

Governance

AdminGate0x8EB93b38B5eFB2eBDa9644580C8682bE00f67c9EOwner of the protocol contracts; driven only through the timelock.
TimelockController0xc47d2A7278eCEF18DC06c614e61C2364d0Eb31f4Admin actions wait 24 h before they apply.
guardian0xE09305576d70B823eA9EBb8873A3Af47D5bFAA4eGuardian Safe (multisig) that proposes timelock actions.

11

Security status

Internally reviewed, unaudited. Findings and fixes are tracked in docs/INTERNAL_AUDIT.md: mutation testing (751 of 766 mutants killed, the rest equivalent), Foundry fuzz and invariant suites, and Halmos symbolic checks of escrow conservation, nullifier single use and deposit caps.

An independent external audit is still required. Until then deposits are capped per asset, and caps rise only through the 24 h timelock.