curl -X POST https://win.oneshotagent.com/v1/tools/physical-mail/approve \
-H "Content-Type: application/json" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=write>" \
-d '{
"quote_id": "00000000-0000-4000-8000-000000000000",
"input_hash": "<the quote'"'"'s input_hash>",
"total_usdc": "<the quote'"'"'s total_usdc>",
"approved": true
}'
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const approval = await agent.physicalMail.approve({
quote_id: quote.quote_id,
input_hash: quote.input_hash,
total_usdc: quote.total_usdc!,
approved: true,
});
approval = client.physical_mail.approve(
quote_id=quote["quote_id"],
input_hash=quote["input_hash"],
total_usdc=quote["total_usdc"],
approved=True,
)
{
"approval_id": "00000000-0000-4000-8000-000000000000",
"quote_id": "00000000-0000-4000-8000-000000000000"
}
{
"error": "quote_changed_or_expired"
}
Physical Mail
Approve a quote
Explicitly approve the exact mailpiece and price of a quote
POST
/
v1
/
tools
/
physical-mail
/
approve
curl -X POST https://win.oneshotagent.com/v1/tools/physical-mail/approve \
-H "Content-Type: application/json" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=write>" \
-d '{
"quote_id": "00000000-0000-4000-8000-000000000000",
"input_hash": "<the quote'"'"'s input_hash>",
"total_usdc": "<the quote'"'"'s total_usdc>",
"approved": true
}'
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const approval = await agent.physicalMail.approve({
quote_id: quote.quote_id,
input_hash: quote.input_hash,
total_usdc: quote.total_usdc!,
approved: true,
});
approval = client.physical_mail.approve(
quote_id=quote["quote_id"],
input_hash=quote["input_hash"],
total_usdc=quote["total_usdc"],
approved=True,
)
{
"approval_id": "00000000-0000-4000-8000-000000000000",
"quote_id": "00000000-0000-4000-8000-000000000000"
}
{
"error": "quote_changed_or_expired"
}
Overview
Records a person’s approval of one quote at one price. Repeat theinput_hash and total_usdc the quote returned: a changed piece or price is refused. Nothing is charged yet. Returns the approval_id that Send needs with the quote_id. Free.
Call this from the approver’s handler after they have seen preview.url and total_usdc, never automatically after a preview. Approving the same quote twice returns the same approval_id.
Authentication
X-Agent-ID plus a signed x-agent-proof with scope: "write", or an access token. See proof authentication. 60 requests a minute per agent.
Request Body
string
required
Quote ID from the preview
string
required
The
input_hash the quote returned (64 hex characters)string
required
The
total_usdc the quote returned, as a decimal stringboolean
required
Must be
true: an explicit approval of this piece at this priceResponse
string
Approval ID to send with the quote
string
The approved quote
curl -X POST https://win.oneshotagent.com/v1/tools/physical-mail/approve \
-H "Content-Type: application/json" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=write>" \
-d '{
"quote_id": "00000000-0000-4000-8000-000000000000",
"input_hash": "<the quote'"'"'s input_hash>",
"total_usdc": "<the quote'"'"'s total_usdc>",
"approved": true
}'
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const approval = await agent.physicalMail.approve({
quote_id: quote.quote_id,
input_hash: quote.input_hash,
total_usdc: quote.total_usdc!,
approved: true,
});
approval = client.physical_mail.approve(
quote_id=quote["quote_id"],
input_hash=quote["input_hash"],
total_usdc=quote["total_usdc"],
approved=True,
)
{
"approval_id": "00000000-0000-4000-8000-000000000000",
"quote_id": "00000000-0000-4000-8000-000000000000"
}
{
"error": "quote_changed_or_expired"
}
Errors
| Code | When |
|---|---|
400 invalid_input | approved is not true, or a field has the wrong shape |
409 quote_changed_or_expired | The quote expired, is still rendering, or input_hash or total_usdc differ from the quote |