Executions

Withdraw an asset to an address on any supported chain

Both live withdrawals and dry: true previews require X-Grant-Token and Idempotency-Key; a live withdrawal also needs an account policy allowing withdrawal to the destination. An archived, deleted or frozen account, or one whose applied policy does not parse (policy_not_ready), gets no preview, and an asset GET /v1/tokens does not list (unsupported_token) or a recipient that is not a valid address (invalid_address) is refused before any provider call, as a live withdrawal is. The account’s rules never refuse a preview: it answers with spend (USD value and budget left), fee (on chain near, the provider’s estimate when stated in the withdrawn asset, otherwise amount minus quote.amount_out; on a confidential bridged route, amount minus quote.amount_out valued in the asset of the same symbol 1Click lists on that chain; null for a public bridged route, when the quote states no amount_out, when the chain lists no single asset of that symbol, when either asset has no fresh price, or when the delivery is worth more than amount) and warnings, which list each rule the live withdrawal would fail under its code (policy_action_denied, policy_destination_denied, policy_asset_denied, schedule, USD budget, per-asset limits, actions per hour, policy_usage_unavailable when unreconciled history keeps the limits from being judged, or insufficient_balance with available_amount) beside high_fee (above 5%, only where fee is valued) and asset_delivered_as_is (a non-USDC asset to hypercore). Identical previews reuse a result for 60 seconds; an expired preview needs a new key. The API sets no preview cap; each preview that reaches the provider counts toward the wallet’s 1,000 custody operations per rolling 24 hours (provider_limit_reached). NEAR (nep141:wrap.near, or near) withdrawn to chain near always arrives as native NEAR, public or confidential.

POST

agents

{agent_id}

withdraw

Withdraw an asset to an address on any supported chain

curl --request POST \
  --url https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Grant-Token: <api-key>' \
  --data '
{
  "asset": "<string>",
  "amount": "<string>",
  "chain": "<string>",
  "recipient": "<string>",
  "memo": "<string>",
  "confidential": false,
  "async": false,
  "dry": false
}
'

import requests

url = "https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw"

payload = {
    "asset": "<string>",
    "amount": "<string>",
    "chain": "<string>",
    "recipient": "<string>",
    "memo": "<string>",
    "confidential": False,
    "async": False,
    "dry": False
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "X-API-Key": "<api-key>",
    "X-Grant-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'X-API-Key': '<api-key>',
    'X-Grant-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    asset: '<string>',
    amount: '<string>',
    chain: '<string>',
    recipient: '<string>',
    memo: '<string>',
    confidential: false,
    async: false,
    dry: false
  })
};

fetch('https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'asset' => '<string>',
    'amount' => '<string>',
    'chain' => '<string>',
    'recipient' => '<string>',
    'memo' => '<string>',
    'confidential' => false,
    'async' => false,
    'dry' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "X-API-Key: <api-key>",
    "X-Grant-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw"

	payload := strings.NewReader("{\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"chain\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"memo\": \"<string>\",\n  \"confidential\": false,\n  \"async\": false,\n  \"dry\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("X-Grant-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("X-API-Key", "<api-key>")
  .header("X-Grant-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"chain\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"memo\": \"<string>\",\n  \"confidential\": false,\n  \"async\": false,\n  \"dry\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-API-Key"] = '<api-key>'
request["X-Grant-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"chain\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"memo\": \"<string>\",\n  \"confidential\": false,\n  \"async\": false,\n  \"dry\": false\n}"

response = http.request(request)
puts response.read_body

{
  "correlation_id": "<string>",
  "agent_id": "<string>",
  "status": "PENDING_SIGNATURE",
  "failure_code": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "dispatch_committed_at": "<string>",
  "grant": {
    "id": "<string>",
    "label": "<string>"
  },
  "type": "agent_create",
  "details": {
    "revision": 4503599627370495,
    "policy_hash": "<string>",
    "transaction_hash": "<string>",
    "agent_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

Authorizations

X-API-Key

string

header

required

X-Grant-Token

string

header

required

Token of the owner grant a delegated request runs under. The partner creates it and the owner signs its commitment; keep it on your backend.

Headers

Idempotency-Key

string

required

Stable key for one logical request. Replays with the same key and body return the original result; a different body is refused with idempotency_conflict.

Required string length: 8 - 128

Pattern: ^[A-Za-z0-9._:-]+$

Path Parameters

agent_id

string

required

Pattern: ^[0-9a-f]{64}$

Body

application/json

asset

string

required

Required string length: 1 - 256

amount

string

required

Pattern: ^(?!0+$)[0-9]{1,78}$

chain

string

required

Required string length: 1 - 64

recipient

string

required

Required string length: 1 - 128

memo

string

Maximum string length: 256

confidential

boolean

default:false

async

boolean

default:false

dry

boolean

default:false

Response

Success

correlation_id

required

Pattern: ^op_[A-Za-z0-9_-]{43}$

agent_id

string | null

required

Pattern: ^[0-9a-f]{64}$

status

enum<string>

required

Available options:

PENDING_SIGNATURE,

QUEUED,

PENDING_APPROVAL,

PENDING_DEPOSIT,

PROCESSING,

SUCCESS,

REFUNDED,

FAILED,

UNCERTAIN,

NEEDS_REVIEW

failure_code

string | null

required

created_at

string

required

updated_at

string

required

dispatch_committed_at

string | null

required

grant

object | null

required

Show child attributes

type

string

required

Allowed value: "agent_create"

details

object

required

Show child attributes

Withdraw an asset to an address on any supported chain

curl --request POST \
  --url https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-API-Key: <api-key>' \
  --header 'X-Grant-Token: <api-key>' \
  --data '
{
  "asset": "<string>",
  "amount": "<string>",
  "chain": "<string>",
  "recipient": "<string>",
  "memo": "<string>",
  "confidential": false,
  "async": false,
  "dry": false
}
'

import requests

url = "https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw"

payload = {
    "asset": "<string>",
    "amount": "<string>",
    "chain": "<string>",
    "recipient": "<string>",
    "memo": "<string>",
    "confidential": False,
    "async": False,
    "dry": False
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "X-API-Key": "<api-key>",
    "X-Grant-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'X-API-Key': '<api-key>',
    'X-Grant-Token': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    asset: '<string>',
    amount: '<string>',
    chain: '<string>',
    recipient: '<string>',
    memo: '<string>',
    confidential: false,
    async: false,
    dry: false
  })
};

fetch('https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'asset' => '<string>',
    'amount' => '<string>',
    'chain' => '<string>',
    'recipient' => '<string>',
    'memo' => '<string>',
    'confidential' => false,
    'async' => false,
    'dry' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "X-API-Key: <api-key>",
    "X-Grant-Token: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw"

	payload := strings.NewReader("{\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"chain\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"memo\": \"<string>\",\n  \"confidential\": false,\n  \"async\": false,\n  \"dry\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("X-Grant-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("X-API-Key", "<api-key>")
  .header("X-Grant-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"chain\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"memo\": \"<string>\",\n  \"confidential\": false,\n  \"async\": false,\n  \"dry\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agentsonintents.com/v1/agents/{agent_id}/withdraw")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-API-Key"] = '<api-key>'
request["X-Grant-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"asset\": \"<string>\",\n  \"amount\": \"<string>\",\n  \"chain\": \"<string>\",\n  \"recipient\": \"<string>\",\n  \"memo\": \"<string>\",\n  \"confidential\": false,\n  \"async\": false,\n  \"dry\": false\n}"

response = http.request(request)
puts response.read_body

{
  "correlation_id": "<string>",
  "agent_id": "<string>",
  "status": "PENDING_SIGNATURE",
  "failure_code": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "dispatch_committed_at": "<string>",
  "grant": {
    "id": "<string>",
    "label": "<string>"
  },
  "type": "agent_create",
  "details": {
    "revision": 4503599627370495,
    "policy_hash": "<string>",
    "transaction_hash": "<string>",
    "agent_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

{
  "errors": [
    {
      "status": "<string>",
      "code": "<string>",
      "layer": "request",
      "title": "<string>",
      "detail": "<string>",
      "source": {
        "pointer": "<string>"
      },
      "meta": {
        "retryable": true,
        "available_at": "2023-11-07T05:31:56Z",
        "min_amount": "<string>",
        "available_amount": "<string>"
      }
    }
  ],
  "meta": {
    "request_id": "<string>"
  }
}

Agent API

Quickstart

Guides

Trust & Verification

API Reference

Withdraw an asset to an address on any supported chain

Authorizations

Headers

Path Parameters

Body

Response