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
STEP 1
Publish a key
Each party signs once to derive an X25519 coordination key and registers the public half (POST /keys).
STEP 2
Open an RFQ
The taker encrypts size and limit to each invited maker (POST /rfqs). The relay stores ciphertext only.
STEP 3
Quote and accept
Makers reply with encrypted quotes; the taker decrypts locally and accepts one (POST /quotes/:id/accept).
STEP 4
Fund the escrow
Both sides get an unsigned tx from POST /settlements/:id/fund and send it from their own wallet.
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.
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":"..."}}- Reads are open. When API keys are configured, every write also needs
x-api-key. - Rate limit: 120 req/min per key, 30 per IP without one. Over the limit returns 429; successful responses carry
x-ratelimit-remaining. - Send
Idempotency-Keyon writes. Same key + same body replays the first answer; same key with a different body is 422. - Request bodies are capped at 256 KiB.
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 | /markets | open | All markets on the chain. |
| GET | /markets/:symbolOrAddress | open | One 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 | /keys | EIP-712 body | Register your coordination public key (KeyRequest). |
| GET | /keys/:owner | open | Look 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 | /rfqs | EIP-712 body | Open an RFQ encrypted to the invited makers. |
| GET | /rfqs | signed read | Your inbox: RFQs you opened or were invited to. |
| GET | /rfqs/:id | signed read | One RFQ. Not a party -> 404. |
| POST | /rfqs/:id/quotes | EIP-712 body | Submit an encrypted quote.quote.rfqId must match the path. |
| POST | /quotes/:id/accept | EIP-712 body | Accept a quote (RFQ maker only). |
| POST | /rfqs/:id/cancel | EIP-712 body | Cancel your RFQ. |
| POST | /rfqs/:id/settlement | EIP-712 body | Link 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/:id | open | Deal 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/:id | open | Receipt 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= | open | On-chain session state and remaining per-call / daily limits. |
| POST | /agents/:agent/simulate | EIP-712 body | Dry-run the full policy pipeline. Nothing executes. |
Webhooks
Need an API key (the key owns the subscription).
| POST | /webhooks | x-api-key | Subscribe { url, events[] }. The secret is returned only in this response. |
| GET | /webhooks | x-api-key | Your subscriptions, without secrets. |
| DELETE | /webhooks/:id | x-api-key | Remove a subscription. |
| GET | /webhooks/:id/deliveries | x-api-key | Last 100 deliveries: status, attempts, lastError. |
| POST | /webhooks/:id/test | x-api-key | Send 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.
| 400 | BAD_REQUEST | Body or parameter failed validation. |
| 400 | UNSUPPORTED_CHAIN | chainId is not served. Use 46630. |
| 401 | UNAUTHENTICATED | Signed read missing or invalid. |
| 401 | API_KEY_REQUIRED | This deployment requires x-api-key on writes. |
| 401 | BAD_API_KEY | Unknown API key. |
| 404 | NOT_FOUND | No such object, or you are not a party to it. |
| 409 | TERMS_MISMATCH | The terms you sent do not hash to this settlement id. |
| 409 | ALREADY_FUNDED | Your side of the escrow is already funded. |
| 409 | AMBIGUOUS_SYMBOL | Two tokens share the symbol. Use the address. |
| 409 | PAST_DEADLINE | Too late to fund. |
| 409 | NOT_EXPIRED | Too early to refund. |
| 413 | TOO_LARGE | Body over 256 KiB. |
| 422 | IDEMPOTENCY_CONFLICT | Same Idempotency-Key, different body. |
| 422 | RELAY_REJECTED | The coordination relay refused the signed request (see message). |
| 429 | RATE_LIMITED | Over 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 sendbo.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 valid08
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_markets | read | List markets. |
| blackout_get_market | read | One market by address or symbol. |
| blackout_list_rfqs | read | The agent's RFQ inbox. |
| blackout_get_rfq_status | read | Status of one RFQ. |
| blackout_get_quotes | read | Decrypted quotes on the agent's RFQ. |
| blackout_get_receipt | read | Public receipt. |
| blackout_get_agent_policy | read | Policy and remaining limits. |
| blackout_simulate_action | read | Run the policy pipeline without acting. |
| blackout_create_rfq | write | Open an encrypted RFQ. |
| blackout_submit_quote | write | Quote on an RFQ (dry-run only in v1). |
| blackout_accept_quote | write | Accept a quote. |
| blackout_fund_settlement | write | Approve + fund the agent's side via the session key. |
| blackout_refund | write | Refund 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.
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
| AgreementEngine | 0xaD3dCC5769A1955220C746A9f33e3C70699bA6A3 | Multi-condition agreements (not exposed to agents in v1). |
| AttestationCondition | 0xD16638a719B3F96EAB761f0539Adb8D11f8c48C3 | Condition: an attester signed off. |
| BilateralEscrow | 0x693cF64F1215625e24d4a916b2C73a0C7d3599AB | Two-sided atomic swap: both deposit and it settles in one tx, or each refunds after the deadline. |
| CompositeCondition | 0x17DFeaCDB915193820D58A8dBaf22B0D1D8A6f22 | AND / OR of other conditions. |
| DeadlineCondition | 0x79577921150c42aa90fb2d60BCb971A74a6C027c | Condition: before a timestamp. |
| SettlementCondition | 0x6EAaA78b17dEdb63c1110F68a222B46b7a87A3DB | Condition: another settlement closed. |
| SettlementFactory | 0x3e91b773FD8Bc2aAba93DB35Ecdd8472B72F0d6e | Deploys settlement instances. |
| SettlementRegistry | 0xEA05C7da1E6332cD366dD40322bfF642c20B204f | Records which ids settled (receipts read it). |
| TimeCondition | 0x739924f8dAC1173f2B20C634De1AFD69c1346e50 | Condition: after a timestamp. |
| owner | 0x8EB93b38B5eFB2eBDa9644580C8682bE00f67c9E | Owner recorded at deploy time. |
Shielded vault & proofs
| AuthorizationVerifier | 0xfEc27E9EBaDdF14A70b63685EFF802403040e9F6 | Verifier for AGENT_AUTHORIZATION proofs. |
| EligibilityVerifier | 0xCA1d74e3a0a46E72335c5A643f0085F869C0ceb9 | Verifier for ELIGIBILITY proofs. |
| FundingCondition | 0xB21ca2b5f8670Fc9062a9c1390A76A160f719D37 | Condition: FUNDING proof present. |
| FundingVerifier | 0x8a1755525af48cF7eD9b1f9D511ce697DA0FCBD3 | Verifier for FUNDING proofs. |
| HonkVerifier | 0xEb9e33356F9fC4B1DBFFCC2E8be0ec74E922Ec29 | Generated UltraHonk verifier for the transact circuit. |
| PriceLimitCondition | 0xdb2FeeC98049C4d8a9D463CAEe3df1472cE86ED4 | Condition: PRICE_LIMIT proof present. |
| PriceLimitVerifier | 0xfee4ca6935977187B2C379e4396011DaE6f60E42 | Verifier for PRICE_LIMIT proofs. |
| ProofCondition | 0x9cC3574c6a8C75f4B15026B8Cb28d39eE7Db2fef | Condition: a valid proof of a given type exists for this settlement. |
| ProofRegistry | 0xAff2139C8BE891025189bC560fc7F40A4CeF43Dc | Stores proof records; isValid checks recorded / revoked / expired / type active. |
| ShieldedVault | 0x3C748fF0d5680e7C5E4C1774F866A26DCfb291cf | Shielded pool: deposit, private transfer, withdraw with a ZK proof. Per-asset deposit cap. |
| owner | 0x8EB93b38B5eFB2eBDa9644580C8682bE00f67c9E | Owner recorded at deploy time. |
| testToken | 0x0000000000000000000000000000000000000000 | Test ERC-20 used for vault demos. |
Governance
| AdminGate | 0x8EB93b38B5eFB2eBDa9644580C8682bE00f67c9E | Owner of the protocol contracts; driven only through the timelock. |
| TimelockController | 0xc47d2A7278eCEF18DC06c614e61C2364d0Eb31f4 | Admin actions wait 24 h before they apply. |
| guardian | 0xE09305576d70B823eA9EBb8873A3Af47D5bFAA4e | Guardian 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.