Orders
Approve Security
Build the approval a seller needs when the security is delivered by allowance
POST
/
orderbooks
/
external-securities
/
api
/
order-books
/
{orderBookId}
/
security-approval
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" }'
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();
}
{
"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"
}
}
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.
The transaction is signed by the seller and targets the security token. Prepare Order 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
Order book whose security and custody contract the approval is for. Must be
ACTIVE and reachable from your instance.Body Parameters
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
Read the current allowance from
securityAllowance on Get Security Status.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" }'
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();
}
{
"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 |
⌘I
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" }'
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();
}
{
"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"
}
}
