Public API

Headless settlement evidence for agents.

api.settleproof.xyz has a visual console at the root and JSON endpoints under /v1/*. Agents use the API to prepare deterministic escrow inputs, inspect registered merchants, bind delivery proof templates, build audit evidence packets, relay fully signed transactions, and read live devnet settlement state without opening the demo UI.

Hosted surfaces

URL	Audience	Purpose
api.settleproof.xyz	humans	API console with endpoint inventory and live protocol status
/openapi.json	agents + SDKs	OpenAPI 3.1 contract for generated clients and API review
/v1/status	agents	JSON status for deployed programs, relay, indexer, and reads
/v1/registry/merchants	agents + merchants	merchant attestor registry with settlement stats
/v1/proof-templates	integrators	delivery proof templates for API, travel, tickets, and commerce
demo.settleproof.xyz	humans + merchants	visual merchant/x402 harness that uses the same protocol path

Endpoint map

Method	Path	Status	Use
GET	/openapi.json	live	OpenAPI 3.1 contract
GET	/v1/status	live	Protocol and deployment status
POST	/v1/escrows/prepare	live	Derive escrow PDA, vault ATA, merchant PDA, and task hash inputs
GET	/v1/escrows/:pda	live	Read one escrow account from devnet
GET	/v1/evidence/:pda	live	Build a liability evidence packet with digest/signature metadata
GET	/v1/merchants/:pubkey	live	Read one registered merchant account from devnet
GET	/v1/registry/merchants	live	List/filter registered merchants, attestor keys, and settlement stats
GET	/v1/proof-templates	live	List reusable delivery proof templates, API/data first
GET	/v1/indexer	live	List escrow accounts from the persistent devnet index
GET	/v1/indexer/events	live	List persisted settlement events
POST	/v1/indexer/sync	live	Trigger a program-account sync into the persistent index
GET	/v1/relay	live	Describe signed-transaction relay policy
POST	/v1/relay	live	Broadcast a base64 serialized, already-signed Solana transaction

Prepare an escrow

/v1/escrows/prepare does not create an escrow. It prepares deterministic addresses and input bytes. The agent still signs locally with its wallet or posts an already-signed transaction to /v1/relay.

curl -s https://api.settleproof.xyz/v1/escrows/prepare \
  -H 'content-type: application/json' \
  -d '{
    "agent_owner": "<agent wallet>",
    "merchant": "<merchant wallet>",
    "mint": "<USDC or mock mint>",
    "amount_stroops": "1000000",
    "ttl_seconds": 3600,
    "task_intent": "GET https://merchant.example/api/report?id=abc"
  }'

{
  "data": {
    "escrow_pda": "...",
    "vault_token_account": "...",
    "agent_token_account": "...",
    "merchant_pda": "...",
    "inputs": {
      "task_hash": "...",
      "task_hash_derived": true,
      "amount_usdc": "1.000000"
    },
    "sdk_call": {
      "package": "@aap/sdk-ts",
      "method": "client.createEscrow",
      "signer": "agent_owner"
    }
  }
}

Headless agent flow

import { SettleProofApiClient, hexToBytes } from "@aap/sdk-ts";

const api = new SettleProofApiClient();
const quote = await api.prepareEscrow(intent);

const { escrowPda } = await client.createEscrow({
  agentOwner,
  merchantPubkey,
  mint,
  amountStroops,
  taskHash: hexToBytes(quote.data.inputs.task_hash),
  ttlSeconds,
});

// Optional: broadcast an already-signed transaction through the public relay.
await api.relaySignedTransaction({
  signed_transaction: signedTxBase64,
  encoding: "base64",
  confirm: true,
});

const merchants = await api.listMerchants({ status: "Active", q: "api" });
const templates = await api.listProofTemplates();
const evidence = await api.getEvidence(escrowPda.toBase58());

Registry, templates, evidence

These endpoints are the competitive layer above raw payment rails: agents can choose registered merchants, bind the task to a delivery template, and later export an evidence packet that shows whether the merchant delivered or the refund path remained enforceable.

curl -s 'https://api.settleproof.xyz/v1/registry/merchants?status=Active&q=api&min_reputation=5000'
curl -s 'https://api.settleproof.xyz/v1/proof-templates?wedge=api-data'
curl -s 'https://api.settleproof.xyz/v1/evidence/<escrow_pda>?download=json'

{
  "data": {
    "version": "settleproof-evidence-v1",
    "purpose": "audit packet proving post-payment delivery settlement state",
    "delivery_claim": {
      "proof_hash": "...",
      "verification": "Ed25519 attestation from registered merchant key"
    },
    "settlement_decision": {
      "status": "released | refunded | pending",
      "reason": "merchant_delivery_proof_verified"
    }
  },
  "signature": {
    "status": "signed | unsigned",
    "digest_sha256": "...",
    "algorithm": "ed25519"
  }
}

Relay policy

No private keys

The public API never receives agent, merchant, or attestor secrets. POST /v1/relay only accepts serialized transactions that have already been signed by the caller.

curl -s https://api.settleproof.xyz/v1/relay

curl -s https://api.settleproof.xyz/v1/relay \
  -H 'content-type: application/json' \
  -d '{
    "signed_transaction": "<base64 serialized signed tx>",
    "encoding": "base64",
    "confirm": true
  }'

Indexer filters

The current hosted indexer syncs live program accounts from Solana devnet into a persistent JSON store. Set INDEXER_STORE_PATH to a Railway volume path if you want the index to survive redeploys.

curl -s 'https://api.settleproof.xyz/v1/indexer?limit=10'
curl -s 'https://api.settleproof.xyz/v1/indexer?merchant=<merchant>&state=Pending'
curl -s 'https://api.settleproof.xyz/v1/indexer/events?limit=10'
curl -s -X POST 'https://api.settleproof.xyz/v1/indexer/sync'