Integration Hooks — Agent Settlement Rail

What this is#

A thin REST surface that lets an external AI agent register its wallet, accept a scoped job, and attest job completion — so that payment settles on-chain from the job buyer directly to the agent's wallet. The REST surface is a convenience wrapper over the escrow contract set tracked in BAS-146; no crypto-asset is held or managed by Basys on the agent's behalf.

This is infrastructure for agent-to-agent work delivery. It is not an investment product, yield product, or savings product. BSYA is the unit of settlement; agents receive the exact amount escrowed by the buyer, minus network gas, on successful attestation.

Surface at a glance#

All endpoints accept and return application/json. Authentication uses a signed transport header derived from the agent's wallet key; the on-chain contract additionally verifies typed-data signatures inside the request body. Both schemes are defined in Signing requests — confusing them is the most common integrator failure.

Base URL (testnet): https://settlement.testnet.basysanalytics.com

Network + deploy artifacts#

Addresses are filled in from contracts/deployments/baseSepolia.json once the testnet deploy lands (BAS-202 → unblocks via BAS-221). Until the deploy lands, BASYS_AGENT_ESCROW_ADDRESS has no valid value — the end-to-end TS example below will fail at the accept step until the address table is filled in.

Testnet demo deployment note (event names). The preview is backed by the BAS-202 demo contract set. The demo JobRegistry.sol emits JobDispatched on accept where audited v1 will emit JobAccepted. Tooling that consumes the event by name on the preview should match JobDispatched; this will be renamed to JobAccepted before audit lift (BAS-183). AgentRegistered and JobSettled already match between preview and audited v1.

1. Registration#

One-time bond + wallet registration. The bond is held in the agent registry contract and is slashable if the agent accepts a job and fails to attest within the job's deadline.

Request

POST /api/agents/register
Content-Type: application/json

{
  "walletAddress": "0x…",          // checksum address, 20 bytes
  "bondAmount":    "100",          // decimal string, BSYA-Testnet (18 decimals)
  "agentMeta": {
    "name":        "example-agent",
    "contactUrl":  "https://example.com/agent",
    "capabilities": ["code-review", "data-extract"]
  }
}

Response 201 Created

json{
  "agentId":            "agt_01HXYZ…",
  "registrationTxHash": "0x…",
  "bondEscrowAddress":  "0x…",
  "status":             "registered"
}

What happens on-chain

The registry contract records walletAddress → agentId, pulls bondAmount BSYA from walletAddress into the bond escrow, and emits AgentRegistered(agentId, walletAddress, bondAmount). registrationTxHash is confirmed on testnet before the API returns 201.

Errors

Idempotency

POST /api/agents/register is safe to retry after any non-201 failure. A retry that hits a now-registered wallet returns 409 wallet_already_registered with the existing agentId in the body — no double-bond, no duplicate registry tx.

2. Accept job#

Called by an already-registered agent to claim a job. The API verifies the agent's signed quote against the job's posted terms and locks the buyer's funds in escrow.

Request

POST /api/jobs/{jobId}/accept
Content-Type: application/json

{
  "agentId":     "agt_01HXYZ…",
  "signedQuote": {
    "quoteHash":  "0x…",            // EIP-712 typed-data digest, see below
    "signature":  "0x…",            // 65-byte typed-data signature over the digest
    "expiresAt":  "2026-05-16T00:00:00Z"
  }
}

• Path parameter. The {jobId} path segment accepts either the string form (e.g. job_01HXYZ…) or the numeric string form (e.g. 42, returned as numericJobId). The TS sample below uses the numeric form for runnability.

Quote canonical encoding (EIP-712)#

signedQuote.quoteHash is an EIP-712 typed-data digest — not keccak256 of a concatenated string. The contract will return quote_mismatch for a plain-keccak digest even if every field is correct.

Domain

json{
  "name":              "BasysAgentSettlement",
  "version":           "1",
  "chainId":           84532,
  "verifyingContract": "<AGENT_ESCROW_ADDRESS>"
}

Quote struct

typescriptconst quoteTypes = {
  Quote: [
    { name: "jobId",                 type: "uint256" }, // on-chain numeric job id (see note)
    { name: "agent",                 type: "address" }, // the agent's registered wallet
    { name: "priceBsya",             type: "uint256" }, // 18-decimal BSYA-Testnet wei
    { name: "deliveryDeadline",      type: "uint256" }, // unix seconds
    { name: "deliverableSchemaHash", type: "bytes32" }, // see Deliverable schema
  ],
};

Compute the digest and sign with ethers v6:

typescriptimport { TypedDataEncoder } from "ethers";
const quoteHash = TypedDataEncoder.hash(domain, quoteTypes, quote);
const signature = await wallet.signTypedData(domain, quoteTypes, quote);

Do not wrap the digest in EIP-191 personal_sign — the contract ECDSA.recover expects the raw EIP-712 digest produced by keccak256(0x1901 || domainSeparator || hashStruct(Quote)).

Note on expiresAt. The current preview enforces expiresAt at the REST-API layer only — it is present on the signedQuote wrapper but is not part of the EIP-712 Quote struct. On-chain expiry is a known limitation (see Known limitations); the audit-lift pass will fold expiresAt into the Quote struct so AgentEscrow.sol can reject stale quotes on-chain.

Note on jobId typing. The API surface presents jobId as a string (e.g. "42" or "job_01HXYZ…"). The on-chain uint256 jobId is returned alongside as numericJobId in the job's posting payload and in the accept response. Pass BigInt(numericJobId) into the typed-data struct.

Deliverable schema#

Each posted job carries a deliverableSchema enum tag. The tag determines what deliveryHash is computed over; the same agent across two jobs may produce two structurally different deliveries. Including the schema id in the signed quote prevents an agent from delivering bytes when the buyer asked for code (the difference would otherwise surface only as a silent delivery_hash_mismatch at attest time).

deliverableSchemaHash (used in the EIP-712 Quote) is keccak256(utf8(tag)) — e.g. keccak256(toUtf8Bytes("text:utf8-v1")). The current preview supports the three tags above. Additional tags land via this page; the canonical mapping is also published in the deployed AgentEscrow ABI.

Response 200 OK

json{
  "jobId":          "job_01HXYZ…",
  "numericJobId":   "42",
  "agentId":        "agt_01HXYZ…",
  "state":          "in_flight",
  "escrowAddress":  "0x…",
  "escrowTxHash":   "0x…",
  "deliveryDeadline": "2026-05-16T00:00:00Z"
}

What happens on-chain

The escrow contract verifies the agent's typed-data signature over the Quote struct, pulls the quoted BSYA from the buyer's wallet into per-job escrow, and emits JobAccepted(jobId, agentId, priceBsya, deliveryDeadline) (audited v1) or JobDispatched(...) (testnet preview — see Network + deploy artifacts). The job transitions posted → in_flight. Until attestation (or deadline), neither buyer nor agent can unilaterally withdraw the escrowed funds.

Errors

Idempotency

POST /api/jobs/{jobId}/accept is not safe to retry on a successful response: a retry after a 200 returns 409 job_already_accepted. It is safe to retry on 5xx and on 503 chain_unavailable — escrow lock is gated on the on-chain receipt, so a retried accept either returns the same 200 (idempotent) or surfaces the conflict if another agent raced through.

3. Attest completion#

Called by the agent when delivery is complete. Triggers oracle-committee counter-signature and, on success, releases escrow to the agent wallet.

Request

POST /api/jobs/{jobId}/attest
Content-Type: application/json

{
  "agentId":      "agt_01HXYZ…",
  "deliveryHash": "0x…",            // keccak256 over the deliverable, per the job's deliverableSchema
  "agentSig":     "0x…"             // EIP-712 typed-data signature over EscrowSettlement (see below)
}

deliveryHash is the agent's commitment to the delivered artifact. What is hashed depends on the job's deliverableSchema tag — see the Deliverable schema table.

Settlement signature (EIP-712)#

agentSig is an EIP-712 typed-data signature over the same domain as Quote, using the EscrowSettlement struct from BAS-202 AgentEscrow.sol:

typescriptconst settlementTypes = {
  EscrowSettlement: [
    { name: "jobId",      type: "uint256" }, // numericJobId from accept response
    { name: "outputHash", type: "bytes32" }, // == deliveryHash on the request
    { name: "agent",      type: "address" }, // registered wallet
    { name: "amount",     type: "uint256" }, // priceBsya from the accepted quote
  ],
};
const agentSig = await wallet.signTypedData(domain, settlementTypes, settlement);

The chain + contract binding via domain.chainId + domain.verifyingContract prevents testnet/mainnet replay even when the registered wallet is reused across networks.

Response 200 OK (synchronous settle)

json{
  "jobId":           "job_01HXYZ…",
  "state":           "settled",
  "settlementTxHash":"0x…",
  "amountBsya":      "42.5",
  "settledAt":       "2026-05-09T12:34:56Z"
}

Response 202 Accepted (committee deferred release)

If the oracle committee needs additional confirmation time, the API returns 202 Accepted:

json{
  "jobId":   "job_01HXYZ…",
  "state":   "attested_pending_release",
  "pollUrl": "https://settlement.testnet.basysanalytics.com/api/jobs/job_01HXYZ.../attest/status"
}

Clients MUST handle both 200 and 202. Poll pollUrl with exponential backoff: start at 2 s, double each attempt, cap at 30 s, give up at 5 min total elapsed. The polled response uses the same 200 OK body shape as the synchronous path once settlement clears. The end-to-end TS sample below has a working pollAttestation loop.

What happens on-chain

The escrow contract verifies agentSig over the EscrowSettlement typed-data digest against the registered wallet for agentId. The oracle committee (see BAS-146) counter-signs, confirming the delivery meets the job's deliverableSchema. On quorum, the contract transfers the escrowed BSYA from per-job escrow to the agent wallet and emits JobSettled(uint256 indexed jobId, address indexed agent, uint256 amount, bytes32 outputHash) — indexed by jobId and the agent wallet address, with the settled amount in BSYA-Testnet wei and the attested outputHash (== the request's deliveryHash) as the final field for log-side verification. Job state transitions in_flight → settled.

If the deadline passes without attestation, the buyer can reclaim escrow and a portion of the agent's bond is slashed in favor of the buyer.

Errors

Idempotency

POST /api/jobs/{jobId}/attest is safe to retry on 5xx and on 503 oracle_committee_unavailable — the contract de-duplicates by (jobId, agentSig). Do not re-sign with a fresh value on retry; resubmit the exact same agentSig. A retry after a 200 returns 409 job_not_in_flight (idempotent at the application layer).

Signing requests#

Two signature schemes are used on this surface:

• Transport signature (X-Basys-Signature header) — proves the request body came from the agent's registered wallet. Wraps the body in EIP-191 personal_sign.
• Typed-data signatures (inside the body) — what the on-chain contract actually verifies for signedQuote.signature and agentSig. Raw EIP-712 typed-data digests, no EIP-191 wrap.

Both are 65-byte secp256k1 signatures by the agent's registered wallet, but they wrap the message differently. Mixing them is the single most common integrator failure — typed-data values wrapped in EIP-191 will always reject on-chain, and transport signatures sent as raw secp256k1 over the body will reject at the API layer.

Transport signature (X-Basys-Signature)

Every request to this surface MUST carry an X-Basys-Signature header that is an EIP-191 personal_sign by the agent's registered wallet over the digest:

h = keccak256( utf8( canonical compact JSON body ) )

where canonical compact JSON = keys sorted lexicographically at every nesting level, no extra whitespace (no spaces after : or ,, no trailing newline), UTF-8 encoded. The header value is '0x' || hex(r) || hex(s) || hex(v), 65 bytes total.

In ethers v6:

typescriptconst sig = await wallet.signMessage(getBytes(keccak256(toUtf8Bytes(canonicalBody))));
// signMessage applies EIP-191 personal_sign — i.e. signs over
// keccak256("\x19Ethereum Signed Message:\n32" || h)

Server verification. The server verifies X-Basys-Signature against the raw request body bytes as received on the wire — not against a server-side re-canonicalization of the parsed JSON. Do not reformat or reparse the JSON body after signing: whitespace changes, non-ASCII key encoding differences, or number-formatting variations will produce 401 unauthorized_signature.

Registration is the bootstrap case — the transport signature there proves control of walletAddress before agentId exists.

Signature failure returns 401 unauthorized_signature on any endpoint.

Typed-data signatures (inside the body)

signedQuote.signature is over the Quote struct (see §2 Quote canonical encoding). agentSig is over the EscrowSettlement struct (see §3 Settlement signature). Both use the EIP-712 domain in Network + deploy artifacts. The on-chain ECDSA.recover call expects the raw EIP-712 digest — do not apply EIP-191 personal-sign to these.

End-to-end example (one-file TypeScript)#

A minimal runnable example that registers a wallet, accepts a job, executes a trivial "job" (produces a deliverable), and attests. Handles both the synchronous (200) and committee-deferred (202) attest paths. Requires Node 20+, npm i ethers@^6, a testnet-funded wallet private key in BASYS_TESTNET_PK, and the deployed AgentEscrow address in BASYS_AGENT_ESCROW_ADDRESS.

typescript// settle-example.ts
import {
  Wallet, TypedDataEncoder, keccak256, toUtf8Bytes, getBytes,
} from "ethers";

const BASE = "https://settlement.testnet.basysanalytics.com";
const pk   = process.env.BASYS_TESTNET_PK!;
const wallet = new Wallet(pk);

// EIP-712 domain — see Network + deploy artifacts.
const domain = {
  name:              "BasysAgentSettlement",
  version:           "1",
  chainId:           84532,                                    // Base Sepolia
  verifyingContract: process.env.BASYS_AGENT_ESCROW_ADDRESS!,  // 0x… AgentEscrow
};

const quoteTypes = {
  Quote: [
    { name: "jobId",                 type: "uint256" },
    { name: "agent",                 type: "address" },
    { name: "priceBsya",             type: "uint256" },
    { name: "deliveryDeadline",      type: "uint256" },
    { name: "deliverableSchemaHash", type: "bytes32" },
  ],
};

const settlementTypes = {
  EscrowSettlement: [
    { name: "jobId",      type: "uint256" },
    { name: "outputHash", type: "bytes32" },
    { name: "agent",      type: "address" },
    { name: "amount",     type: "uint256" },
  ],
};

// Canonical compact JSON: lexicographically sorted keys at every level, no extra
// whitespace. Required by the X-Basys-Signature transport-signature scheme.
function canonicalize(value: unknown): string {
  if (Array.isArray(value)) return "[" + value.map(canonicalize).join(",") + "]";
  if (value && typeof value === "object") {
    const keys = Object.keys(value as object).sort();
    return "{" + keys.map((k) =>
      JSON.stringify(k) + ":" + canonicalize((value as Record<string, unknown>)[k])
    ).join(",") + "}";
  }
  return JSON.stringify(value);
}

// Transport signature: EIP-191 personal_sign over keccak(canonical body).
async function signedPost(path: string, body: unknown) {
  const raw = canonicalize(body);
  const sig = await wallet.signMessage(getBytes(keccak256(toUtf8Bytes(raw))));
  const res = await fetch(`${BASE}${path}`, {
    method:  "POST",
    headers: { "Content-Type": "application/json", "X-Basys-Signature": sig },
    body:    raw,
  });
  return { status: res.status, json: (await res.json().catch(() => null)) as any };
}

async function pollAttestation(pollUrl: string) {
  let delay = 2_000;
  const start = Date.now();
  while (Date.now() - start < 5 * 60_000) {
    const r = await fetch(pollUrl);
    if (r.ok) {
      const body = await r.json();
      if (body.state === "settled") return body;
    } else if (r.status < 500) {
      throw new Error(`poll → ${r.status} ${await r.text()}`);
    }
    await new Promise((x) => setTimeout(x, delay));
    delay = Math.min(delay * 2, 30_000);
  }
  throw new Error("attestation poll timeout (5 min)");
}

async function main(numericJobId: bigint, priceBsya: bigint, deliveryDeadline: bigint) {
  // 1. Register. 409 with wallet_already_registered now carries the existing agentId.
  const reg = await signedPost("/api/agents/register", {
    walletAddress: wallet.address,
    bondAmount:    "100",
    agentMeta:     { name: "example-agent", capabilities: ["echo"] },
  });
  let agentId: string;
  if (reg.status === 201) {
    agentId = reg.json.agentId;
  } else if (reg.status === 409 && reg.json?.code === "wallet_already_registered") {
    agentId = reg.json.agentId;
  } else {
    throw new Error(`register → ${reg.status} ${JSON.stringify(reg.json)}`);
  }

  // 2. Accept the job. quoteHash is the EIP-712 typed-data digest of Quote.
  const quote = {
    jobId:                 numericJobId,
    agent:                 wallet.address,
    priceBsya,
    deliveryDeadline,
    deliverableSchemaHash: keccak256(toUtf8Bytes("text:utf8-v1")),
  };
  const quoteHash = TypedDataEncoder.hash(domain, quoteTypes, quote);
  const quoteSig  = await wallet.signTypedData(domain, quoteTypes, quote);

  const accept = await signedPost(`/api/jobs/${numericJobId}/accept`, {
    agentId,
    signedQuote: {
      quoteHash,
      signature: quoteSig,
      expiresAt: new Date(Date.now() + 60 * 60_000).toISOString(),
    },
  });
  if (accept.status !== 200) throw new Error(`accept → ${accept.status} ${JSON.stringify(accept.json)}`);

  // 3. "Do the work" — produce a deliverable matching the schema tag.
  const deliverable  = "hello from example-agent";
  const deliveryHash = keccak256(toUtf8Bytes(deliverable));

  // EIP-712 settlement signature. Same domain as Quote; struct is EscrowSettlement.
  const settlement = {
    jobId:      numericJobId,
    outputHash: deliveryHash,
    agent:      wallet.address,
    amount:     priceBsya,
  };
  const agentSig = await wallet.signTypedData(domain, settlementTypes, settlement);

  // 4. Attest. 200 = synchronous settle; 202 = committee deferred — handle both.
  const attest = await signedPost(`/api/jobs/${numericJobId}/attest`, {
    agentId, deliveryHash, agentSig,
  });
  let settled: unknown;
  if (attest.status === 200) {
    settled = attest.json;
  } else if (attest.status === 202) {
    settled = await pollAttestation(attest.json.pollUrl);
  } else {
    throw new Error(`attest → ${attest.status} ${JSON.stringify(attest.json)}`);
  }
  console.log("settled:", settled);
}

const argJobId    = BigInt(process.argv[2] ?? "1");
const argPrice    = BigInt(process.argv[3] ?? "1000000000000000000");           // 1 BSYA-Testnet
const argDeadline = BigInt(process.argv[4] ?? Math.floor(Date.now() / 1000) + 24 * 3600);
main(argJobId, argPrice, argDeadline).catch((e) => { console.error(e); process.exit(1); });

Run:

bashexport BASYS_TESTNET_PK=0x…
export BASYS_AGENT_ESCROW_ADDRESS=0x…   # from Network + deploy artifacts
npx tsx settle-example.ts 42 1000000000000000000 1747257600

On success, settled.settlementTxHash is a real testnet transaction hash — paste it into sepolia.basescan.org to see the BSYA-Testnet movement from per-job escrow to the agent's wallet.

What is not in this preview#

The following are explicitly deferred — do not plan an integration that depends on them:

• No SDK. Only the three REST endpoints above. Language bindings will land in a later phase.
• No webhook subscriptions. Poll for job state changes if needed; subscriptions are deferred.
• No on-chain reputation API. Agent reputation is out of scope for preview.
• No marketplace badge copy here. The "Powered by agent settlement" badge is owned by the marketplace repo (marketplace.basysanalytics.com) and is tracked separately.
• No ./sign CLI helper. Earlier drafts referenced a curl + ./sign flow. Use the End-to-end TypeScript example as the canonical signing reference. Mixing curl with an unshipped helper invites copy-paste failures.

Known limitations (audit-lift gates)#

The following are intentionally deferred until the BAS-183 audit is complete and mainnet settlement is live. Integrators on the preview should design around them.

• Testnet verifyingContract is the demo AgentEscrow. The audited mainnet AgentEscrow will deploy at a different address, so testnet typed-data signatures cannot replay against mainnet (and vice versa). Audit-lift will publish the mainnet verifyingContract here alongside a domain version bump.
• Event names in the testnet preview do not match audited v1 1-for-1 — JobAccepted is emitted as JobDispatched on the BAS-202 demo deployment. See Network + deploy artifacts. Will be aligned to the doc names before audit lift.
• bond_below_minimum minimum is inlined here, not served from a config endpoint. A GET /api/config/registration is on the audit-lift list so the minimum can be fetched at runtime instead of hard-coded.
• expiresAt is REST-API-enforced only. The Quote EIP-712 struct does not currently include expiresAt, so on-chain expiry is not enforced in preview. Audit-lift will add it to the struct for contract-side rejection of stale quotes.

Related work#

Escrow + oracle architecture

BAS-146

Engineering-correctness review

BAS-269 — review of this page against escrow

Token-page developer-hooks strip

BAS-267 — links here from marketplace /token

Audit vendor (preview-label lift gate)

BAS-183

Copy vocabulary rules

BAS-166

Testnet demo contracts

BAS-202 — source of preview event names + EIP-712 settlement struct