# WorxAI.tech API Reference

## Zero-Latency Data Pipeline API v2

WorxAI exposes an ACADS gateway for autonomous systems. Requests combine the data query, replay nonce, agent signature, and Permit2 authorization in one payload.

## Production endpoint

```text
POST https://worxai.tech/api/v2/procure
Content-Type: application/json
```

## Request schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agentWallet` | Hex address | Yes | The autonomous agent wallet address. |
| `pipeline` | string | Yes | `/v2/ledger` or `/v2/behavioral`. |
| `parameters` | object | Yes | Query constraints such as `{ "limit": 1000 }`. |
| `nonce` | string | Yes | Unique, incrementing request nonce. |
| `signature` | Hex string | Yes | EIP-712 signature over the request payload. |
| `permit2` | object | Yes | Permit2 authorization package. |

### Permit2 object

```json
{
  "amount": "10000",
  "deadline": "1815782400",
  "signature": "0x..."
}
```

`amount` is expressed in micro-USDC. `35000` equals `0.035 USDC`, the minimum transaction amount. The maximum transaction amount is `5000000000` micro-USDC ($5,000). `deadline` is a Unix timestamp and must be in the future.

## Example request

```json
{
  "agentWallet": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "pipeline": "/v2/ledger",
  "parameters": { "limit": 1000 },
  "nonce": "1718293842",
  "signature": "0x539c3629e46a782a472a1e06915b81a1796be82688827c1f8069d31191542f741275bb2442db237190b4931a7e1c8d06b5cf62a36b12a83e0c0f82bb1c5a932b1b",
  "permit2": {
    "amount": "10000",
    "deadline": "1815782400",
    "signature": "0x7a8b3f2c...e8d9c2b1"
  }
}
```

## Responses

### Success — `200 OK`

The gateway returns data only after structural validation, replay checks, signature verification, and credit-risk checks succeed.

```json
[
  {
    "timestamp": "2026-08-27T10:32:15.192Z",
    "transaction_id": "tx_example_1000",
    "account_root": "0xAlphaLedgerNode",
    "amount": "4392.12",
    "asset": "USDC"
  }
]
```

### Replay or expired authorization — `403 Forbidden`

```json
{
  "error": "Forbidden",
  "message": "Payload signature expired or previously executed."
}
```

### Credit lockout — `403 Forbidden`

```json
{
  "error": "Forbidden",
  "message": "Pipeline routing access suspended. Wallet carries outstanding unresolved collection items."
}
```

## Verification flow

1. The agent creates the signed request and Permit2 authorization.
2. The agent sends the payload to `/api/v2/procure`.
3. The gateway validates the wallet, pipeline, parameters, nonce, deadline, signature, recipient, token, and replay state.
4. The gateway records authorization before returning protected data.
5. Settlement can be completed asynchronously on Base.

## Discovery endpoints

- `/api/gateway/discovery`
- `/api/gateway/health`
- `/api/gateway/capabilities`
- `/api/gateway/fees`
- `/api/gateway/intents`
- `/api/gateway/receipts`
- `/api/schema`
- `/llms.txt`
- `/llms-full.txt`
- `/pipeline-registry.json`
- `/API_REFERENCE.md`

## Complete endpoint directory

- Payments: `/api/quote`, `/api/payment/verify`, `/api/datasets/download`
- Gateway payments: `/api/gateway/payments/verify`, `/api/gateway/payments/settle`
- x402: `/api/gateway/x402/verify`, `/api/gateway/x402/settle`
- Protected data: `/api/ledger`, `/api/behavioral`, `/api/v2/procure`
- Credit: `/api/credit/status`
- Operations: `/api/admin/overview`, `/api/analytics/visit`
- Dataset files: `/api/datasets/file`

## Security notes

Never embed private keys in client code, manifests, shell scripts, or source control. Treat example hashes and signatures as illustrative only. Consumers should validate the response status and avoid retrying a request with the same nonce after a successful authorization.

## Registry

Pipeline metadata is published in `/pipeline-registry.json`. The Solidity registry source is available at `contracts/PipelineRegistry.sol`; registration is owner-only and deployments are intentionally not broadcast by this repository.