Grant RAMS Mandate

Prepare RAMS grant mandate

curl --request POST \
  --url https://api.sandbox.brickken.com/x402/rams/grant-mandate \
  --header 'Content-Type: application/json' \
  --header 'X-Payment: <api-key>' \
  --data '
{
  "chainId": "11155111",
  "agent": "<string>",
  "principal": "<string>",
  "validUntil": 123,
  "identityRef": "<string>",
  "asset": "<string>",
  "maxTransactionValue": "<string>",
  "maxCumulativeValue": "<string>",
  "actions": [
    "<string>"
  ],
  "signerAddress": "<string>",
  "validFrom": 123,
  "complianceProvider": "<string>",
  "metadata": "<string>",
  "signature": "<string>",
  "deadline": "<string>",
  "executionMode": "brickken-relayed",
  "agentMandateAddress": "<string>",
  "gasLimit": "<string>",
  "nonce": 123,
  "ownerEmail": "jsmith@example.com",
  "email": "jsmith@example.com"
}
'

import requests

url = "https://api.sandbox.brickken.com/x402/rams/grant-mandate"

payload = {
    "chainId": "11155111",
    "agent": "<string>",
    "principal": "<string>",
    "validUntil": 123,
    "identityRef": "<string>",
    "asset": "<string>",
    "maxTransactionValue": "<string>",
    "maxCumulativeValue": "<string>",
    "actions": ["<string>"],
    "signerAddress": "<string>",
    "validFrom": 123,
    "complianceProvider": "<string>",
    "metadata": "<string>",
    "signature": "<string>",
    "deadline": "<string>",
    "executionMode": "brickken-relayed",
    "agentMandateAddress": "<string>",
    "gasLimit": "<string>",
    "nonce": 123,
    "ownerEmail": "jsmith@example.com",
    "email": "jsmith@example.com"
}
headers = {
    "X-Payment": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Payment': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    chainId: '11155111',
    agent: '<string>',
    principal: '<string>',
    validUntil: 123,
    identityRef: '<string>',
    asset: '<string>',
    maxTransactionValue: '<string>',
    maxCumulativeValue: '<string>',
    actions: ['<string>'],
    signerAddress: '<string>',
    validFrom: 123,
    complianceProvider: '<string>',
    metadata: '<string>',
    signature: '<string>',
    deadline: '<string>',
    executionMode: 'brickken-relayed',
    agentMandateAddress: '<string>',
    gasLimit: '<string>',
    nonce: 123,
    ownerEmail: 'jsmith@example.com',
    email: 'jsmith@example.com'
  })
};

fetch('https://api.sandbox.brickken.com/x402/rams/grant-mandate', 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.sandbox.brickken.com/x402/rams/grant-mandate",
  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([
    'chainId' => '11155111',
    'agent' => '<string>',
    'principal' => '<string>',
    'validUntil' => 123,
    'identityRef' => '<string>',
    'asset' => '<string>',
    'maxTransactionValue' => '<string>',
    'maxCumulativeValue' => '<string>',
    'actions' => [
        '<string>'
    ],
    'signerAddress' => '<string>',
    'validFrom' => 123,
    'complianceProvider' => '<string>',
    'metadata' => '<string>',
    'signature' => '<string>',
    'deadline' => '<string>',
    'executionMode' => 'brickken-relayed',
    'agentMandateAddress' => '<string>',
    'gasLimit' => '<string>',
    'nonce' => 123,
    'ownerEmail' => 'jsmith@example.com',
    'email' => 'jsmith@example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Payment: <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.sandbox.brickken.com/x402/rams/grant-mandate"

	payload := strings.NewReader("{\n  \"chainId\": \"11155111\",\n  \"agent\": \"<string>\",\n  \"principal\": \"<string>\",\n  \"validUntil\": 123,\n  \"identityRef\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"maxTransactionValue\": \"<string>\",\n  \"maxCumulativeValue\": \"<string>\",\n  \"actions\": [\n    \"<string>\"\n  ],\n  \"signerAddress\": \"<string>\",\n  \"validFrom\": 123,\n  \"complianceProvider\": \"<string>\",\n  \"metadata\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"deadline\": \"<string>\",\n  \"executionMode\": \"brickken-relayed\",\n  \"agentMandateAddress\": \"<string>\",\n  \"gasLimit\": \"<string>\",\n  \"nonce\": 123,\n  \"ownerEmail\": \"jsmith@example.com\",\n  \"email\": \"jsmith@example.com\"\n}")

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

	req.Header.Add("X-Payment", "<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.sandbox.brickken.com/x402/rams/grant-mandate")
  .header("X-Payment", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"chainId\": \"11155111\",\n  \"agent\": \"<string>\",\n  \"principal\": \"<string>\",\n  \"validUntil\": 123,\n  \"identityRef\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"maxTransactionValue\": \"<string>\",\n  \"maxCumulativeValue\": \"<string>\",\n  \"actions\": [\n    \"<string>\"\n  ],\n  \"signerAddress\": \"<string>\",\n  \"validFrom\": 123,\n  \"complianceProvider\": \"<string>\",\n  \"metadata\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"deadline\": \"<string>\",\n  \"executionMode\": \"brickken-relayed\",\n  \"agentMandateAddress\": \"<string>\",\n  \"gasLimit\": \"<string>\",\n  \"nonce\": 123,\n  \"ownerEmail\": \"jsmith@example.com\",\n  \"email\": \"jsmith@example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.brickken.com/x402/rams/grant-mandate")

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

request = Net::HTTP::Post.new(url)
request["X-Payment"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"chainId\": \"11155111\",\n  \"agent\": \"<string>\",\n  \"principal\": \"<string>\",\n  \"validUntil\": 123,\n  \"identityRef\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"maxTransactionValue\": \"<string>\",\n  \"maxCumulativeValue\": \"<string>\",\n  \"actions\": [\n    \"<string>\"\n  ],\n  \"signerAddress\": \"<string>\",\n  \"validFrom\": 123,\n  \"complianceProvider\": \"<string>\",\n  \"metadata\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"deadline\": \"<string>\",\n  \"executionMode\": \"brickken-relayed\",\n  \"agentMandateAddress\": \"<string>\",\n  \"gasLimit\": \"<string>\",\n  \"nonce\": 123,\n  \"ownerEmail\": \"jsmith@example.com\",\n  \"email\": \"jsmith@example.com\"\n}"

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

{
  "data": {
    "transactions": {},
    "txId": "<string>",
    "info": {}
  }
}

POST

x402

rams

grant-mandate

Prepare RAMS grant mandate

curl --request POST \
  --url https://api.sandbox.brickken.com/x402/rams/grant-mandate \
  --header 'Content-Type: application/json' \
  --header 'X-Payment: <api-key>' \
  --data '
{
  "chainId": "11155111",
  "agent": "<string>",
  "principal": "<string>",
  "validUntil": 123,
  "identityRef": "<string>",
  "asset": "<string>",
  "maxTransactionValue": "<string>",
  "maxCumulativeValue": "<string>",
  "actions": [
    "<string>"
  ],
  "signerAddress": "<string>",
  "validFrom": 123,
  "complianceProvider": "<string>",
  "metadata": "<string>",
  "signature": "<string>",
  "deadline": "<string>",
  "executionMode": "brickken-relayed",
  "agentMandateAddress": "<string>",
  "gasLimit": "<string>",
  "nonce": 123,
  "ownerEmail": "jsmith@example.com",
  "email": "jsmith@example.com"
}
'

import requests

url = "https://api.sandbox.brickken.com/x402/rams/grant-mandate"

payload = {
    "chainId": "11155111",
    "agent": "<string>",
    "principal": "<string>",
    "validUntil": 123,
    "identityRef": "<string>",
    "asset": "<string>",
    "maxTransactionValue": "<string>",
    "maxCumulativeValue": "<string>",
    "actions": ["<string>"],
    "signerAddress": "<string>",
    "validFrom": 123,
    "complianceProvider": "<string>",
    "metadata": "<string>",
    "signature": "<string>",
    "deadline": "<string>",
    "executionMode": "brickken-relayed",
    "agentMandateAddress": "<string>",
    "gasLimit": "<string>",
    "nonce": 123,
    "ownerEmail": "jsmith@example.com",
    "email": "jsmith@example.com"
}
headers = {
    "X-Payment": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Payment': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    chainId: '11155111',
    agent: '<string>',
    principal: '<string>',
    validUntil: 123,
    identityRef: '<string>',
    asset: '<string>',
    maxTransactionValue: '<string>',
    maxCumulativeValue: '<string>',
    actions: ['<string>'],
    signerAddress: '<string>',
    validFrom: 123,
    complianceProvider: '<string>',
    metadata: '<string>',
    signature: '<string>',
    deadline: '<string>',
    executionMode: 'brickken-relayed',
    agentMandateAddress: '<string>',
    gasLimit: '<string>',
    nonce: 123,
    ownerEmail: 'jsmith@example.com',
    email: 'jsmith@example.com'
  })
};

fetch('https://api.sandbox.brickken.com/x402/rams/grant-mandate', 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.sandbox.brickken.com/x402/rams/grant-mandate",
  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([
    'chainId' => '11155111',
    'agent' => '<string>',
    'principal' => '<string>',
    'validUntil' => 123,
    'identityRef' => '<string>',
    'asset' => '<string>',
    'maxTransactionValue' => '<string>',
    'maxCumulativeValue' => '<string>',
    'actions' => [
        '<string>'
    ],
    'signerAddress' => '<string>',
    'validFrom' => 123,
    'complianceProvider' => '<string>',
    'metadata' => '<string>',
    'signature' => '<string>',
    'deadline' => '<string>',
    'executionMode' => 'brickken-relayed',
    'agentMandateAddress' => '<string>',
    'gasLimit' => '<string>',
    'nonce' => 123,
    'ownerEmail' => 'jsmith@example.com',
    'email' => 'jsmith@example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Payment: <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.sandbox.brickken.com/x402/rams/grant-mandate"

	payload := strings.NewReader("{\n  \"chainId\": \"11155111\",\n  \"agent\": \"<string>\",\n  \"principal\": \"<string>\",\n  \"validUntil\": 123,\n  \"identityRef\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"maxTransactionValue\": \"<string>\",\n  \"maxCumulativeValue\": \"<string>\",\n  \"actions\": [\n    \"<string>\"\n  ],\n  \"signerAddress\": \"<string>\",\n  \"validFrom\": 123,\n  \"complianceProvider\": \"<string>\",\n  \"metadata\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"deadline\": \"<string>\",\n  \"executionMode\": \"brickken-relayed\",\n  \"agentMandateAddress\": \"<string>\",\n  \"gasLimit\": \"<string>\",\n  \"nonce\": 123,\n  \"ownerEmail\": \"jsmith@example.com\",\n  \"email\": \"jsmith@example.com\"\n}")

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

	req.Header.Add("X-Payment", "<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.sandbox.brickken.com/x402/rams/grant-mandate")
  .header("X-Payment", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"chainId\": \"11155111\",\n  \"agent\": \"<string>\",\n  \"principal\": \"<string>\",\n  \"validUntil\": 123,\n  \"identityRef\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"maxTransactionValue\": \"<string>\",\n  \"maxCumulativeValue\": \"<string>\",\n  \"actions\": [\n    \"<string>\"\n  ],\n  \"signerAddress\": \"<string>\",\n  \"validFrom\": 123,\n  \"complianceProvider\": \"<string>\",\n  \"metadata\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"deadline\": \"<string>\",\n  \"executionMode\": \"brickken-relayed\",\n  \"agentMandateAddress\": \"<string>\",\n  \"gasLimit\": \"<string>\",\n  \"nonce\": 123,\n  \"ownerEmail\": \"jsmith@example.com\",\n  \"email\": \"jsmith@example.com\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.brickken.com/x402/rams/grant-mandate")

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

request = Net::HTTP::Post.new(url)
request["X-Payment"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"chainId\": \"11155111\",\n  \"agent\": \"<string>\",\n  \"principal\": \"<string>\",\n  \"validUntil\": 123,\n  \"identityRef\": \"<string>\",\n  \"asset\": \"<string>\",\n  \"maxTransactionValue\": \"<string>\",\n  \"maxCumulativeValue\": \"<string>\",\n  \"actions\": [\n    \"<string>\"\n  ],\n  \"signerAddress\": \"<string>\",\n  \"validFrom\": 123,\n  \"complianceProvider\": \"<string>\",\n  \"metadata\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"deadline\": \"<string>\",\n  \"executionMode\": \"brickken-relayed\",\n  \"agentMandateAddress\": \"<string>\",\n  \"gasLimit\": \"<string>\",\n  \"nonce\": 123,\n  \"ownerEmail\": \"jsmith@example.com\",\n  \"email\": \"jsmith@example.com\"\n}"

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

{
  "data": {
    "transactions": {},
    "txId": "<string>",
    "info": {}
  }
}

Maps to ramsGrantMandate. The principal must already be eligible with the selected ComplianceProvider.

Authorization modes

Mode	`signerAddress`	Signature fields
Direct	Principal	Omit `signature`; the transaction encodes `0x`
Principal signature	Any transaction sender/relayer	`signature` and the same `deadline` returned by Typed Data
Brickken relayed	Brickken relayer	Principal signature fields plus `executionMode: "brickken-relayed"`

Key fields

agent, principal, validUntil, identityRef, asset, both value caps, and at least one actions entry are required. validFrom defaults to immediate. Values are raw base units; caps accept max/unlimited. Actions accept bytes32 values or 4-byte selectors.

Response

Returns txId, unsigned transactions, and info with the contract, authorization mode, and EIP-712 nonce when applicable. Preparing is free; x402 is charged at send.

Next step

Preparing does not touch the chain. The response gives you txId, the unsigned transactions, and an x402Requirements quote.

Choose who signs and who broadcasts

brickken-relayed — the relayer signs, broadcasts, and pays the native gas; you sign only the payment, and prepare is free. client-signed (the default) — you sign, Brickken broadcasts. client-broadcast — you sign and broadcast yourself, then confirm with txHash. Both client-controlled modes charge half the price at prepare and half at send.Relaying is available on the ERC-8004 and agent-token facades and on the four signed RAMS lifecycle calls. The other RAMS operations check msg.sender against an on-chain role, so they reject it.

Submit it and settle the payment

POST to /send-transactions. The first attempt answers 402 Payment Required; read PAYMENT-REQUIRED, sign the payment locally, and retry with X-PAYMENT. An API key is accepted here only in client-signed mode.

Poll until it confirms

Call GET /get-transaction-status with the txId. Relayed transactions need no credential to poll. Your payment settles only after the operation confirms, and is released if it reverts.

See Authentication for the payment handshake and Pricing for the per-operation cost.

Authorizations

X-Payment

string

header

required

Base64-encoded x402 payment payload. Supported for x402-eligible agentic methods on /x402/... facades, /prepare-transactions, and eligible /send-transactions retries.

Body

application/json

chainId

string

default:11155111

required

Target operation chain ID. RAMS is available on Ethereum Sepolia (11155111) only at launch. Decimal and 0x hex values are accepted.

Examples:

"11155111"

"0xaa36a7"

agent

string

required

Agent wallet receiving the mandate.

Pattern: ^0x[a-fA-F0-9]{40}$

principal

string

required

Principal delegating authority. Direct mode: must equal signerAddress.

Pattern: ^0x[a-fA-F0-9]{40}$

validUntil

required

Mandate expiry. Must be greater than now and greater than validFrom. Unix timestamp in seconds (uint48).

identityRef

string

required

Compliance identity reference (bytes32, 0x + 64 hex). Must match the principal's record on the compliance provider.

Pattern: ^0x[a-fA-F0-9]{64}$

asset

string

required

Asset (token) the mandate is scoped to.

Pattern: ^0x[a-fA-F0-9]{40}$

maxTransactionValue

required

Per-transaction value cap. Alias "max" / "unlimited" (case-insensitive) = 2^256-1 (no cap). Raw base units — no decimals scaling is applied. Decimal string (canonical), 0x hex string, or number accepted.

maxCumulativeValue

required

Cumulative value cap over the mandate lifetime. Alias "max" / "unlimited" = 2^256-1 (no cap). Raw base units — no decimals scaling is applied. Decimal string (canonical), 0x hex string, or number accepted.

actions

string[]

required

Allowed actions. Each item is a bytes32 action or a 4-byte function selector, e.g. 0x23b872dd for transferFrom.

Minimum array length: 1

bytes32 action (0x + 64 hex) or 4-byte selector (0x + 8 hex). Selectors are normalized by right-padding to 32 bytes (left-aligned, Solidity bytes32(selector)).

signerAddress

string

Required for direct/client-signed mode. Omit for brickken-relayed execution; Brickken supplies its operation signer.

Pattern: ^0x[a-fA-F0-9]{40}$

validFrom

Mandate start time. Defaults to 0 (immediately valid). Unix timestamp in seconds (uint48).

complianceProvider

string

Compliance provider contract chosen by the principal. Must be non-zero. Defaults to the chain's configured RAMS ComplianceProvider address.

Pattern: ^0x[a-fA-F0-9]{40}$

metadata

string

Optional opaque metadata (bytes32). Defaults to the zero value.

Pattern: ^0x[a-fA-F0-9]{64}$

signature

string

Optional EIP-712 signature from the principal (never the operator). At least 65 bytes for EOAs (r||s||v); longer payloads are allowed for EIP-1271 contract wallets. Omit for direct mode (the transaction sender authorizes on-chain). Obtain the payload to sign from GET /rams/typed-data/{operation}.

Pattern: ^0x([a-fA-F0-9]{2})*$

deadline

Unix-seconds signature deadline (uint256). Required when signature is provided and must be greater than now — it must equal the deadline that was signed. Ignored (encoded as 0) in direct mode.

executionMode

enum<string>

Optional. Only valid together with signature + deadline: Brickken's relayer becomes the transaction sender and the on-chain authorization rides on the principal's EIP-712 signature. Omit for client-signed execution (default on all /x402/rams facades).

Available options:

brickken-relayed

agentMandateAddress

string

Optional AgentMandate contract override; defaults to the chain's configured RAMS AgentMandate address.

Pattern: ^0x[a-fA-F0-9]{40}$

gasLimit

Optional explicit gas limit.

nonce

number

Optional explicit transaction nonce when managing nonces manually.

ownerEmail

string<email>

Optional owner attribution email.

string<email>

Alias for ownerEmail where supported.

Response

Prepared unsigned transaction payload.

data

object

Show child attributes

Overview

Agent Identity

Reputation

Agent Token Operations

RAMS Mandates (ERC-8226)

RAMS Reads & Typed Data

Authorization modes

Key fields

Response

Next step

Authorizations

Body

Response

​Authorization modes

​Key fields

​Response

​Next step

Authorizations

Body

Response

Authorization modes

Key fields

Response

Next step