Lots

Lots are batched on-chain transfers that group multiple payouts together for efficient blockchain settlement. This endpoint allows you to query lot details for reconciliation and transparency.

Lots are only available for payout (pay) transactions. Each lot contains one or more payouts and may include associated refunds.

List Lots

GET /v1/lots

List lots by date range. Returns a paginated list of lots for the authenticated user.

Query Parameters

Name	Type	Description
start_date	datetime	Required. Start of date range (ISO 8601 format).
end_date	datetime	Required. End of date range (ISO 8601 format).
limit	int	Maximum results to return (1-1000). Default: 100.
offset	int	Pagination offset. Default: 0.

Maximum date range is 31 days. For longer periods, make multiple requests with different date ranges.

Example Request

const params = new URLSearchParams({
  start_date: '2026-01-01T00:00:00Z',
  end_date: '2026-01-28T23:59:59Z',
  limit: '100',
  offset: '0'
});

const url = `${baseURL}/v1/lots?${params}`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
});

import requests

params = {
    'start_date': '2026-01-01T00:00:00Z',
    'end_date': '2026-01-28T23:59:59Z',
    'limit': 100,
    'offset': 0
}

url = f"{base_url}/v1/lots"

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',
}

response = requests.get(url, params=params, headers=headers)

package main

import (
  "fmt"
  "net/http"
  "net/url"
)

func main() {
  baseURL := "https://api.kamipay.io"
  params := url.Values{}
  params.Add("start_date", "2026-01-01T00:00:00Z")
  params.Add("end_date", "2026-01-28T23:59:59Z")
  params.Add("limit", "100")
  params.Add("offset", "0")

  url := fmt.Sprintf("%s/v1/lots?%s", baseURL, params.Encode())

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", access_token))
  req.Header.Add("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    fmt.Println("Error:", err)
    return
  }
  defer resp.Body.Close()
}

Response

{
  "lots": [
    {
      "lot_id": "9c030c8b-6d68-445b-8048-1bacd91012fa",
      "transaction_hash": "0x812f8c44ee5dffe3ff057c3c83e01ed24c613140f25881bc931f0b90635f5bdf",
      "usdt_amount": "10027.79968000",
      "created_at": "2025-05-07T19:36:52.907905Z",
      "status": "MINED"
    },
    {
      "lot_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "transaction_hash": "0xprocessing123456789012345678901234567890123456789012345678901234",
      "usdt_amount": "100.00000000",
      "created_at": null,
      "status": "PROCESSING"
    }
  ],
  "total": 2,
  "limit": 100,
  "offset": 0
}

Date range validation error

{
  "detail": "Date range cannot exceed 31 days"
}

Invalid date order

{
  "detail": "end_date must be after start_date"
}

{
  "detail": "Incorrect Credentials"
}

Get Lot Details

GET /v1/lots/{lot_identifier}

Get complete lot details including all payouts and refunds associated with the lot.

Path Parameters

Name	Type	Description
lot_identifier	string	Required. Either a `lot_id` or a `transaction_hash`.

Flexible lookup: You can use either the lot ID or the blockchain transaction hash to retrieve lot details.

lot_id: UUID format (e.g., 9c030c8b-6d68-445b-8048-1bacd91012fa)
transaction_hash: 0x-prefixed, 66 characters (e.g., 0x812f8c44...5bdf)

Example Request

// Using lot_id (UUID)
const lot_identifier = "9c030c8b-6d68-445b-8048-1bacd91012fa";
// Or using transaction hash
// const lot_identifier = "0x812f8c44ee5dffe3ff057c3c83e01ed24c613140f25881bc931f0b90635f5bdf";

const url = `${baseURL}/v1/lots/${lot_identifier}`;

const response = await fetch(url, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
});

import requests

# Using lot_id (UUID)
lot_identifier = "9c030c8b-6d68-445b-8048-1bacd91012fa"
# Or using transaction hash
# lot_identifier = "0x812f8c44ee5dffe3ff057c3c83e01ed24c613140f25881bc931f0b90635f5bdf"

url = f"{base_url}/v1/lots/{lot_identifier}"

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',
}

response = requests.get(url, headers=headers)

package main

import (
  "fmt"
  "net/http"
)

func main() {
  // Using lot_id (UUID)
  lotIdentifier := "9c030c8b-6d68-445b-8048-1bacd91012fa"
  // Or using transaction hash
  // lotIdentifier := "0x812f8c44ee5dffe3ff057c3c83e01ed24c613140f25881bc931f0b90635f5bdf"

  url := fmt.Sprintf("%s/v1/lots/%s", baseURL, lotIdentifier)

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("Authorization", fmt.Sprintf("Bearer %s", access_token))
  req.Header.Add("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    fmt.Println("Error:", err)
    return
  }
  defer resp.Body.Close()
}

Response

{
  "lot_id": "9c030c8b-6d68-445b-8048-1bacd91012fa",
  "transaction_hash": "0x812f8c44ee5dffe3ff057c3c83e01ed24c613140f25881bc931f0b90635f5bdf",
  "usdt_amount": "10027.79968000",
  "created_at": "2025-05-07T19:36:52.907905Z",
  "status": "MINED",
  "payouts": [
    {
      "kamipay_id": "txc_test_lot1_charge_001",
      "amount": "0.88924200",
      "created_at": "2025-05-07T19:07:19.720238Z"
    },
    {
      "kamipay_id": "txc_test_lot1_charge_002",
      "amount": "0.91518000",
      "created_at": "2025-05-07T19:07:19.720510Z"
    },
    {
      "kamipay_id": "txc_test_lot1_charge_003",
      "amount": "0.89025300",
      "created_at": "2025-05-07T19:07:19.720568Z"
    }
  ],
  "refunds": [
    {
      "kamipay_refund_id": "rpt_test_lot1_refund_001",
      "amount": "0.38102800",
      "created_at": "2025-05-07T19:24:47.821896Z"
    },
    {
      "kamipay_refund_id": "rpt_test_lot1_refund_002",
      "amount": "0.53415200",
      "created_at": "2025-05-07T19:24:47.822305Z"
    }
  ]
}

{
  "detail": "Incorrect Credentials"
}

{
  "detail": "Lot not found"
}

Lot Status Values

Status	Description
`PENDING`	Lot is created but not yet sent on-chain.
`PROCESSING`	Lot transaction is being processed on the blockchain.
`MINED`	Lot transaction has been confirmed on-chain.
`FAILED`	Lot transaction failed. Individual payouts may be retried in a new lot.

Use Cases

Reconciliation

Use the lots endpoint to reconcile your payout records with on-chain transactions:

Query lots for a date range using GET /v1/lots
For each lot, verify the transaction_hash on the blockchain
Cross-reference the payouts array with your internal records using kamipay_id
Account for any refunds that occurred after the lot was settled

Tracking Payout Status

To find which lot contains a specific payout:

Use GET /v1/lots with the appropriate date range
Search through the payouts array in each lot's details
Match using the kamipay_id from your payout response

Tip: Store the lot_id or transaction_hash when you receive the payout webhook for easier future lookups.

Lots

On this page