# Pre-trade hooks and holds (AI agents)

> Tickwire API reference, generated from the OpenAPI document the services export. Base URL: https://api.tickwire.io. Replace YOUR_API_KEY and YOUR_ACCOUNT_ID with your own values; use a sandbox key (twsk_…) to experiment.

Source: https://tickwire.io/docs/reference/pretrade/

### GET /v1/pretrade-holds

**List Holds**

Auth: `X-API-Key`

Holds, newest first (`created_at`, then `id`). Cursor-paginated:
`{data, has_more, next_cursor}`; the cursor is bound to `status` and
`account_id`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | `string \| null` | no |  |
| `account_id` | query | `string \| null` | no |  |
| `limit` | query | `integer` | no | Page size, 1..500 (default 100). |
| `cursor` | query | `string \| null` | no | The next_cursor of the previous page, unchanged. |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `500, 502` [`backend_error`](https://tickwire.io/docs/errors/backend_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/v1/pretrade-holds' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/v1/pretrade-holds",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/v1/pretrade-holds");
console.log(result);
tw.close();
```

### GET /v1/pretrade-holds/{hold_id}

**Get Hold**

Auth: `X-API-Key`

One hold.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `hold_id` | path | `string` | yes |  |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `500, 502` [`backend_error`](https://tickwire.io/docs/errors/backend_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/v1/pretrade-holds/HOLD_ID' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/v1/pretrade-holds/HOLD_ID",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/v1/pretrade-holds/HOLD_ID");
console.log(result);
tw.close();
```

### POST /v1/pretrade-holds/{hold_id}/cancel

**Cancel Hold**

Auth: `X-API-Key`

Owner override: reject a pending hold. Nothing is sent.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `hold_id` | path | `string` | yes |  |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `500, 502` [`backend_error`](https://tickwire.io/docs/errors/backend_error/)

curl:

```bash
curl -sS -X POST 'https://api.tickwire.io/v1/pretrade-holds/HOLD_ID/cancel' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "POST",
        "/v1/pretrade-holds/HOLD_ID/cancel",
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("POST", "/v1/pretrade-holds/HOLD_ID/cancel", {
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### POST /v1/pretrade-holds/{hold_id}/release

**Release Hold**

Auth: `X-API-Key`

Approve or reject a hold; signed with the holding hook's secret.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `hold_id` | path | `string` | yes |  |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `500, 502` [`backend_error`](https://tickwire.io/docs/errors/backend_error/)

curl:

```bash
curl -sS -X POST 'https://api.tickwire.io/v1/pretrade-holds/HOLD_ID/release' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "POST",
        "/v1/pretrade-holds/HOLD_ID/release",
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("POST", "/v1/pretrade-holds/HOLD_ID/release", {
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### GET /v1/pretrade-hooks

**List Hooks**

Auth: `X-API-Key`

This tenant's hooks (never the secrets), oldest first.
Cursor-paginated: `{data, has_more, next_cursor}`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | `integer` | no | Page size, 1..500 (default 100). |
| `cursor` | query | `string \| null` | no | The next_cursor of the previous page, unchanged. |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `500, 502` [`backend_error`](https://tickwire.io/docs/errors/backend_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/v1/pretrade-hooks' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/v1/pretrade-hooks",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/v1/pretrade-hooks");
console.log(result);
tw.close();
```

### POST /v1/pretrade-hooks

**Create Hook** · takes `Idempotency-Key`

Auth: `X-API-Key`

Register a pre-trade decision hook. The `secret` is shown once.

`Idempotency-Key` is honoured: a replay returns the same hook without
registering another, with `secret: null` and a `secret_notice`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | `string \| null` | no |  |
| `X-Actor` | header | `string \| null` | no |  |
| `X-Reason` | header | `string \| null` | no |  |

Request body: `object` (required)

Responses:

- `201` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `409` [`idempotency_conflict`](https://tickwire.io/docs/errors/idempotency_conflict/)
- `500, 502` [`backend_error`](https://tickwire.io/docs/errors/backend_error/)

curl:

```bash
curl -sS -X POST 'https://api.tickwire.io/v1/pretrade-hooks' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: my-request-1' \
  -H 'X-Reason: why you are doing this' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/pretrade","account_id":"YOUR_ACCOUNT_ID"}'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "POST",
        "/v1/pretrade-hooks",
        json={
            "url": "https://example.com/pretrade",
            "account_id": "YOUR_ACCOUNT_ID",
        },
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("POST", "/v1/pretrade-hooks", {
  body: {"url":"https://example.com/pretrade","account_id":"YOUR_ACCOUNT_ID"},
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### GET /v1/pretrade-hooks/{hook_id}

**Get Hook**

Auth: `X-API-Key`

One hook.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `hook_id` | path | `string` | yes |  |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `500, 502` [`backend_error`](https://tickwire.io/docs/errors/backend_error/)

curl:

```bash
curl -sS -X GET 'https://api.tickwire.io/v1/pretrade-hooks/HOOK_ID' \
  -H 'X-API-Key: YOUR_API_KEY'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "GET",
        "/v1/pretrade-hooks/HOOK_ID",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("GET", "/v1/pretrade-hooks/HOOK_ID");
console.log(result);
tw.close();
```

### PATCH /v1/pretrade-hooks/{hook_id}

**Patch Hook**

Auth: `X-API-Key`

Change url, applies_to, fail_mode, timeout, hold TTL or enabled.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `hook_id` | path | `string` | yes |  |
| `X-Actor` | header | `string \| null` | no |  |
| `X-Reason` | header | `string \| null` | no |  |

Request body: `object` (required)

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `500, 502` [`backend_error`](https://tickwire.io/docs/errors/backend_error/)

curl:

```bash
curl -sS -X PATCH 'https://api.tickwire.io/v1/pretrade-hooks/HOOK_ID' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-Reason: why you are doing this' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/pretrade"}'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "PATCH",
        "/v1/pretrade-hooks/HOOK_ID",
        json={"url": "https://example.com/pretrade"},
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("PATCH", "/v1/pretrade-hooks/HOOK_ID", {
  body: {"url":"https://example.com/pretrade"},
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### DELETE /v1/pretrade-hooks/{hook_id}

**Delete Hook**

Auth: `X-API-Key`

Remove a hook. Its pending holds stay pending until they expire.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `hook_id` | path | `string` | yes |  |
| `X-Actor` | header | `string \| null` | no |  |
| `X-Reason` | header | `string \| null` | no |  |

Responses:

- `204` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `500, 502` [`backend_error`](https://tickwire.io/docs/errors/backend_error/)

curl:

```bash
curl -sS -X DELETE 'https://api.tickwire.io/v1/pretrade-hooks/HOOK_ID' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'X-Reason: why you are doing this'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "DELETE",
        "/v1/pretrade-hooks/HOOK_ID",
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("DELETE", "/v1/pretrade-hooks/HOOK_ID", {
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```

### POST /v1/pretrade-hooks/{hook_id}/rotate-secret

**Rotate Hook Secret** · takes `Idempotency-Key`

Auth: `X-API-Key`

Issue a new signing secret (shown once); the old one stops working.
With `Idempotency-Key` a replay rotates nothing and answers `secret:
null` with a `secret_notice`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `hook_id` | path | `string` | yes |  |
| `Idempotency-Key` | header | `string \| null` | no |  |
| `X-Actor` | header | `string \| null` | no |  |
| `X-Reason` | header | `string \| null` | no |  |

Responses:

- `200` Successful Response
- `422` Validation Error (`HTTPValidationError`)

Common errors:

- `401` [`unauthorized`](https://tickwire.io/docs/errors/unauthorized/)
- `429` [`rate_limited`](https://tickwire.io/docs/errors/rate_limited/)
- `400, 422` [`validation_error`](https://tickwire.io/docs/errors/validation_error/)
- `409` [`idempotency_conflict`](https://tickwire.io/docs/errors/idempotency_conflict/)
- `500, 502` [`backend_error`](https://tickwire.io/docs/errors/backend_error/)

curl:

```bash
curl -sS -X POST 'https://api.tickwire.io/v1/pretrade-hooks/HOOK_ID/rotate-secret' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Idempotency-Key: my-request-1' \
  -H 'X-Reason: why you are doing this'
```

Python:

```python
from tickwire import Tickwire

with Tickwire("https://api.tickwire.io", "YOUR_API_KEY") as tw:
    result = tw.request(
        "POST",
        "/v1/pretrade-hooks/HOOK_ID/rotate-secret",
        idempotency_key="my-request-1",
        reason="why you are doing this",
    )
    print(result)
```

TypeScript:

```typescript
import { TickwireClient } from "@tickwire/sdk";

const tw = new TickwireClient({ baseUrl: "https://api.tickwire.io", token: "YOUR_API_KEY" });
const result = await tw.request("POST", "/v1/pretrade-hooks/HOOK_ID/rotate-secret", {
  idempotencyKey: "my-request-1",
  reason: "why you are doing this",
});
console.log(result);
tw.close();
```