> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-generated-reference-full-stack-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v0/wallet/buy-traffic-requests

> Create a request to buy traffic. Note that this only creates the request to do so. Refer to the status endpoint to check if the request succeeded.

<div class="x2mdx-ref-page x2mdx-ref-page--operation x2mdx-ref-page--manual-api" />

<div class="x2mdx-ref-hero">
  <p class="x2mdx-ref-summary">Create a request to buy traffic. Note that this only creates the request to do so. Refer to the status endpoint to check if the request succeeded.</p>

  <div class="x2mdx-ref-badges">
    <span class="x2mdx-ref-badge x2mdx-ref-badge--protocol">OpenAPI</span>

    <a class="x2mdx-ref-badge x2mdx-ref-badge--added" href="#history-added-0-5-10">Added 0.5.10</a>
  </div>
</div>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://example.com/api/validator/v0/wallet/buy-traffic-requests' \
    --header 'Authorization: Bearer $TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
    "receiving_validator_party_id": "<string>",
    "domain_id": "<string>",
    "traffic_amount": 123,
    "tracking_id": "<string>",
    "expires_at": 123
  }'
  ```

  ```python Python theme={null}
  import json
  import requests

  url = "https://example.com/api/validator/v0/wallet/buy-traffic-requests"
  headers = {'Authorization': 'Bearer <token>', 'Content-Type': 'application/json'}
  payload = json.loads(r'''{
    "receiving_validator_party_id": "<string>",
    "domain_id": "<string>",
    "traffic_amount": 123,
    "tracking_id": "<string>",
    "expires_at": 123
  }''')
  response = requests.request(
      "POST", url, headers=headers, json=payload
  )

  print(response.text)
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://example.com/api/validator/v0/wallet/buy-traffic-requests', {
    method: 'POST',
    headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
    body: JSON.stringify({
    "receiving_validator_party_id": "<string>",
    "domain_id": "<string>",
    "traffic_amount": 123,
    "tracking_id": "<string>",
    "expires_at": 123
  }),
  });

  console.log(await response.text());
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
      CURLOPT_URL => 'https://example.com/api/validator/v0/wallet/buy-traffic-requests',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_CUSTOMREQUEST => 'POST',
      CURLOPT_POSTFIELDS => <<<'JSON'
  {
    "receiving_validator_party_id": "<string>",
    "domain_id": "<string>",
    "traffic_amount": 123,
    "tracking_id": "<string>",
    "expires_at": 123
  }
  JSON,
      CURLOPT_HTTPHEADER => [
          "Authorization: Bearer <token>",
          "Content-Type: application/json"
      ],
  ]);

  $response = curl_exec($curl);
  echo $response;
  ```

  ```go Go theme={null}
  package main

  import (
    "bytes"
    "fmt"
    "io"
    "net/http"
  )

  func main() {
    req, _ := http.NewRequest("POST", "https://example.com/api/validator/v0/wallet/buy-traffic-requests", bytes.NewBufferString(`{
    "receiving_validator_party_id": "<string>",
    "domain_id": "<string>",
    "traffic_amount": 123,
    "tracking_id": "<string>",
    "expires_at": 123
  }`))
    req.Header.Set("Authorization", "Bearer <token>")
    req.Header.Set("Content-Type", "application/json")
    response, _ := http.DefaultClient.Do(req)
    defer response.Body.Close()
    body, _ := io.ReadAll(response.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  var request = HttpRequest.newBuilder()
      .uri(URI.create("https://example.com/api/validator/v0/wallet/buy-traffic-requests"))
      .header("Authorization", "Bearer <token>")
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("""
  {
    "receiving_validator_party_id": "<string>",
    "domain_id": "<string>",
    "traffic_amount": 123,
    "tracking_id": "<string>",
    "expires_at": 123
  }
  """))
      .build();
  var response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString());
  System.out.println(response.body());
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'uri'

  uri = URI('https://example.com/api/validator/v0/wallet/buy-traffic-requests')
  request = Net::HTTP::Post.new(uri)
  request['Authorization'] = 'Bearer <token>'
  request['Content-Type'] = 'application/json'
  request.body = <<~JSON
  {
    "receiving_validator_party_id": "<string>",
    "domain_id": "<string>",
    "traffic_amount": 123,
    "tracking_id": "<string>",
    "expires_at": 123
  }
  JSON
  response = Net::HTTP.start(uri.hostname, uri.port) do |http|
    http.request(request)
  end
  puts response.body
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "request_contract_id": "<string>"
  }
  ```

  ```json 400 theme={null}
  {
    "error": "<string>"
  }
  ```

  ```json 409 theme={null}
  {
    "error": "<string>"
  }
  ```

  ```json 429 theme={null}
  {
    "error": "<string>"
  }
  ```

  ```json 500 theme={null}
  {
    "error": "<string>"
  }
  ```
</ResponseExample>

## Authorizations

### walletUserAuth

<ParamField header="Authorization" type="string" required>
  HTTP bearer authentication. Send the token as `Authorization: Bearer &lt;token&gt;`. Bearer format: `JWT`. JWT token as described by the `spliceAppBearerAuth` security scheme. The subject of the token must be ledger API user of the user whose wallet the endpoint affects.
</ParamField>

## Body

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ParamField body="receiving_validator_party_id" type="string" required>
  Traffic will be purchased for the validator hosting this party. If the party is hosted on multiple participants, the request will fail with 400 Bad Request.
</ParamField>

<ParamField body="domain_id" type="string" required>
  The domain to purchase traffic for.
</ParamField>

<ParamField body="traffic_amount" type="number" required>
  OpenAPI type: <code>integer (int64)</code>.

  traffic to purchase in bytes.
</ParamField>

<ParamField body="tracking_id" type="string" required>
  Tracking id to support exactly once submission. Once submitted, all succeessive calls with the same tracking id will get rejected with a 409 or 429 status code unless the command fails and the traffic did not get purchased. Clients should create a fresh tracking id when they try to send a new request to buy traffic. If that command submission fails with a retryable error or the application crashed and got restarted, successive command submissions must reuse the same tracking id to ensure they don't purchase traffic multiple times.
</ParamField>

<ParamField body="expires_at" type="number" required>
  OpenAPI type: <code>integer (int64)</code>.

  Expiry time of the request to buy traffic as unix timestamp in microseconds. If the request does not succeed before this time, the wallet automation will reject and expire it. Note that this time is compared against the ledger effective time of the Daml transaction accepting or expiring an offer, and can skew from the wall clock time measured on the caller's machine. See [https://docs.daml.com/concepts/time.html](https://docs.daml.com/concepts/time.html) for how ledger effective time is bound to the record time of a transaction on a domain.
</ParamField>

## Responses

### 200

Request to buy traffic got created

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="request_contract_id" type="string" required />

### 400

Request was invalid, adjust parameters

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="error" type="string" required />

### 409

A request to buy traffic with the same tracking id has been created. Check the status endpoint for the current status.

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="error" type="string" required />

### 429

A request to buy traffic with the same tracking id is currently being processed. Check the status endpoint and resubmit if it returns 404.

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="error" type="string" required />

### 500

Internal server error that requires operator investigation. Retrying for a small number of times with exponential back-off MAY work.

<div class="x2mdx-ref-badges">
  <span class="x2mdx-ref-badge x2mdx-ref-badge--neutral">application/json</span>
</div>

<ResponseField name="error" type="string" required />

## History

<div class="x2mdx-ref-history" aria-label="Reference history">
  <div class="x2mdx-ref-history-event x2mdx-ref-history-event--introduced" id="history-added-0-5-10">
    <div class="x2mdx-ref-history-event-head">
      <span class="x2mdx-ref-history-event-label">Added</span>
      <code class="x2mdx-ref-history-event-version">0.5.10</code>
    </div>
  </div>
</div>