> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Approve Security

> Build the approval a seller needs when the security is delivered by allowance

Returns unsigned `approve` calldata letting the custody contract deliver the security from a seller's wallet at settlement.

Sellers need this only when the security uses `TRANSFER` delivery. The custody contract then moves the security with `transferFrom`, and the token runs its own transfer rules. Without an allowance a sell order's tradable balance reads as zero, because the venue reports the lesser of the unfrozen balance and the allowance. A security under `AGENT` delivery moves by forced transfer and ignores this allowance. See [Delivery modes](https://docs.trusset.org/endpoints/external-securities-trading/introduction.md#delivery-modes).

The transaction is signed by the seller and targets the security token. [Prepare Order](https://docs.trusset.org/endpoints/external-securities-trading/prepare-order.md) reports the amount a sell order needs in `approval.required`, which covers the order and the seller's other resting sell orders together. The custody contract can only use the allowance to settle a sell order the seller signed.

## Path Parameters

**orderBookId** `string` *required*

Order book whose security and custody contract the approval is for. Must be `ACTIVE` and reachable from your instance.

## Body Parameters

**amount** `string` *required*

Allowance to set, in the security's base units, as a digit-only string. This replaces any existing allowance rather than adding to it.

## Response Fields

**data** `object`

**action** `string`

`SIGN_TRANSACTION`.

**transaction** `object`

**to** `string`

The security token contract.

**data** `string`

Encoded `approve` calldata.

**functionName** `string`

`approve`.

**description** `string`

The spender and amount the approval covers.

> [!NOTE]
>
> Read the current allowance from `securityAllowance` on [Get Security Status](https://docs.trusset.org/endpoints/external-securities-trading/get-security-status.md).

```bash cURL theme={null}
curl -X POST "https://api.trusset.org/orderbooks/external-securities/api/order-books/clx_ob_extsec_001/security-approval" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "10000000000000000000" }'
```

```typescript TypeScript theme={null}
const prep = await fetch(
  'https://api.trusset.org/orderbooks/external-securities/api/orders/prepare',
  {
    method: 'POST',
    headers: { 'X-API-Key': 'trusset_your_key_here', 'Content-Type': 'application/json' },
    body: JSON.stringify({ orderBookId, userAddress: await seller.getAddress(), side: 'SELL', price, quantity })
  }
).then(r => r.json());

const approval = prep.data.approval;
if (approval && !approval.sufficient) {
  const res = await fetch(
    `https://api.trusset.org/orderbooks/external-securities/api/order-books/${orderBookId}/security-approval`,
    {
      method: 'POST',
      headers: { 'X-API-Key': 'trusset_your_key_here', 'Content-Type': 'application/json' },
      body: JSON.stringify({ amount: approval.required })
    }
  );
  const { data } = await res.json();
  const tx = await seller.sendTransaction(data.transaction);
  await tx.wait();
}
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "action": "SIGN_TRANSACTION",
    "transaction": {
      "to": "0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912",
      "data": "0x095ea7b3..."
    },
    "functionName": "approve",
    "description": "Approve 0x489aee4ae9546081d55848f157e03192e826988c to deliver up to 10000000000000000000 of 0x51f2b9d0e77c4a1b83ce6d4a9271e5f3a0c8b912 when your sell orders settle"
  }
}
```

## Error Codes

| Code | HTTP | Cause |
| - | - | - |
| `VALIDATION_ERROR` | `400` | `amount` is missing or not a digit-only string |
| `INSTANCE_REQUIRED` | `400` | The request carried no resolvable instance |
| `ORDER_BOOK_INACTIVE` | `400` | The book is `PAUSED` or `CLOSED` |
| `ORDER_BOOK_NOT_FOUND` | `404` | The book does not exist, is not reachable, or is not an external securities book |
| `SERVICE_NOT_ENABLED` | `403` | The Trading service is not enabled on this instance |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.