Skip to main content

​
Overview

This guide demonstrates how to use the OneShot SDK to perform a real-world commercial action: sending an email from a provisioned domain.

​
Prerequisites

  • A cryptographic wallet
  • Compatible tokens on a supported chain
1

Get a Quote

First, get a pricing quote for sending an email:
curl -X POST https://win.oneshotagent.com/v1/tools/email/quote \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <your_x402_payment_proof>" \
  -d '{
    "from_address": "[email protected]",
    "to_address": "[email protected]",
    "subject": "Hello from OneShot",
    "body": "This is my first email!"
  }'
Response:
{
  "domain": "yourdomain.com",
  "is_new": true,
  "available": true,
  "registration_fee": 10.00,
  "service_fee": 0.01,
  "total_cost": 10.01,
  "currency": "USD",
  "quote_id": "quote_abc123"
}
2

Handle 402 Payment Required

When you call the API without payment, it returns a 402 Payment Required response with all the payment details:
{
  "error": "payment_required",
  "code": 402,
  "payment_info": {
    "protocol": "x402",
    "network": "8453",
    "payTo": "0x1234...5678",
    "amount": "10.01",
    "currency": "USDC",
    "token": {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "symbol": "USDC",
      "decimals": 6
    }
  }
}
Create a cryptographic transfer authorization using the payment info:
// Extract from 402 response
const { payTo, amount, token } = paymentInfo;

// Sign authorization
const signature = await wallet.sign({
  from: yourWalletAddress,
  to: payTo, // Treasury address from API
  value: parseUnits(amount, token.decimals),
  validAfter: 0,
  validBefore: Math.floor(Date.now() / 1000) + 3600,
  nonce: randomBytes(32)
});
3

Send Email

Use the quote ID and payment proof to send the email:
curl -X POST https://win.oneshotagent.com/v1/tools/email/send \
  -H "Content-Type: application/json" \
  -H "X-Payment-Proof: <your_x402_signature>" \
  -d '{
    "quote_id": "quote_abc123",
    "from_address": "[email protected]",
    "to_address": "[email protected]",
    "subject": "Hello from OneShot",
    "body": "This is my first email!"
  }'
Response:
{
  "request_id": "req_xyz789",
  "status": "processing",
  "message": "Email job queued successfully"
}
4

Poll for Replies

Check for inbound emails (replies):
curl -X GET "https://win.oneshotagent.com/v1/tools/inbox?include_body=true&limit=10" \
  -H "X-Agent-ID: <your_agent_uuid>"
Response:
{
  "emails": [
    {
      "id": "email_123",
      "from": "[email protected]",
      "subject": "Re: Hello from OneShot",
      "body": "Thanks for reaching out!",
      "received_at": "2025-12-28T12:00:00Z",
      "attachments": []
    }
  ],
  "count": 1,
  "has_more": false
}

​
Next Steps

SDK Overview

Learn how the SDK handles commercial actions

API Reference

Explore all available endpoints