API Reference

REST API Reference

All Fixer Protocol gateway endpoints. The SDK wraps these, use the REST API directly when you need language-level control or are not using TypeScript/Python.

Authentication

Every API request must include your API key as a Bearer token in the Authorization header, and your agentId in the X-Agent-Id header.

bash

curl https://api.fixerprotocol.org/v1/wallet/my-agent \
  -H "Authorization: Bearer $FIXER_API_KEY" \
  -H "X-Agent-Id: my-agent" \
  -H "Content-Type: application/json"

Base URL

text

https://api.fixerprotocol.org

Required headers

Authorization

string

required

Bearer <API_KEY>: your API key from the dashboard.

X-Agent-Id

string

required

The agent identifier. Must match the agent associated with your API key.

Content-Type

string

optional

Required for POST/PUT requests: application/json.

Idempotency-Key

string

optional

Client-supplied key for idempotent write operations. A duplicate request with the same key returns the original response.

Rate limits

The API applies two layers of rate limiting:

Gateway rate limit: 1000 requests/minute per API key (applies across all endpoints)
Spend policy rate limit: per-agent rate limit configured via PUT /v1/policies/{agentId}

When a rate limit is hit, the API returns HTTP 429 with a Retry-After header indicating when you may retry.

Payments

POST /v1/pay Route a transparent payment

Route a payment to any payment-gated service endpoint. The gateway detects the required protocol (x402 or MPP) automatically and handles all handshake and settlement logic. Payments settle on Solana in under 1 second.

Request body

agentId

string

required

The agent making the payment. Must match X-Agent-Id header.

endpoint

string

required

Full HTTPS URL of the service to call.

method

string

optionaldefault: "GET"

HTTP method: "GET", "POST", "PUT", "PATCH", "DELETE".

body

object | null

optional

Request body forwarded to the upstream service after payment resolves.

headers

object

optional

Additional headers to forward to the upstream service.

idempotencyKey

string

optional

Client idempotency key for safe retries.

Response 200 OK

json

{
  "status": 200,
  "txHash": "5xGh9KmBvPqR3sTuWxYzAcBdEf7jKLMnPqR2sTuWx",
  "amountPaid": { "usdc": 0.002 },
  "protocol": "x402",
  "data": { ... }
}

Example request

bash

curl -X POST https://api.fixerprotocol.org/v1/pay \
  -H "Authorization: Bearer $FIXER_API_KEY" \
  -H "X-Agent-Id: my-agent" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "my-agent",
    "endpoint": "https://api.dune.com/api/v1/query/3326266/results",
    "method": "GET"
  }'

POST /v1/pay/private Route a ZK-private payment

Same as POST /v1/pay but wraps the transaction in a Groth16 zero-knowledge proof. Amount, sender, and receiver privacy depend on the privacy.mode selected.

Additional request body fields

privacy.mode

string

required

"transparent": no privacy (same as /v1/pay)
"confidential_amount": hides payment amount only
"full": hides amount, sender, and receiver

privacy.disclosureKey

string

optional

A public key (base58 Solana address) that can decrypt the transaction details. Generates a disclosureProof in the response.

Response 200 OK

json

{
  "status": 200,
  "txHash": "4nLm8...nullifier_hash",
  "amountPaid": { "usdc": 0.002 },
  "protocol": "x402",
  "data": { ... },
  "privateNote": "encrypted_commitment_for_your_records",
  "disclosureProof": "zk_viewing_credential"
}

Wallet

GET /v1/wallet/{agentId} Get wallet info and balance

Path parameters

agentId

string

required

The agent ID whose wallet you want to inspect.

Response 200 OK

json

{
  "agentId": "my-agent",
  "address": "7xKXtg2eH9sZ7pWbRqTJ3mQfJLxxxx",
  "balance": { "usdc": 42.50 }
}

POST /v1/wallet/{agentId}/fund Top up wallet balance

Request body

usdc

number

required

USDC amount to deposit. Must be a positive number.

idempotencyKey

string

optional

Prevents duplicate funding operations.

Response 200 OK

json

{
  "txHash": "7KLMnPqR2sTuWxYzAcBdEf7jKLMn",
  "amount": { "usdc": 100 },
  "balance": { "usdc": 142.50 }
}

Transactions

GET /v1/transactions List transactions with filters

Query parameters

agentId

string

required

Filter to a specific agent's transactions.

limit

number

optionaldefault: 20

Number of results. Maximum: 100.

offset

number

optionaldefault: 0

Pagination offset.

protocol

"x402" | "mpp"

optional

Filter by payment protocol.

from

string

optional

ISO 8601 start date (inclusive).

string

optional

ISO 8601 end date (inclusive).

Response 200 OK

json

{
  "transactions": [
    {
      "txHash": "5xGh9KmBv...",
      "agentId": "my-agent",
      "endpoint": "https://api.dune.com/api/v1/query/...",
      "amount": { "usdc": 0.002 },
      "protocol": "x402",
      "timestamp": "2026-05-30T14:22:03Z",
      "status": "confirmed",
      "solanaTxLink": "https://explorer.solana.com/tx/5xGh9KmBv...",
      "parentTxHash": null
    }
  ],
  "total": 147,
  "hasMore": true
}

GET /v1/transactions/{txHash} Get single transaction

Path parameters

txHash

string

required

The Solana transaction hash returned from a payment call.

Returns the same Transaction object shape as the list endpoint.

Policies

GET /v1/policies/{agentId} Get current spend policy

Returns the currently active spend policy for the specified agent. Returns an empty object {} if no policy has been set (all spending unconstrained).

json

{
  "dailyBudget": { "usdc": 100 },
  "perCallLimit": { "usdc": 1.00 },
  "allowedDomains": ["api.dune.com", "api.browserbase.com"],
  "blockedDomains": [],
  "rateLimit": { "calls": 500, "window": "1h" }
}

PUT /v1/policies/{agentId} Set or replace spend policy

Replaces the agent's full spend policy. All fields are optional, omit a field to leave it unconstrained. Policies are enforced immediately on the next payment attempt.

Request body

json

{
  "dailyBudget":    { "usdc": 100 },
  "perCallLimit":   { "usdc": 1.00 },
  "allowedDomains": ["api.dune.com", "api.browserbase.com", "fal.ai"],
  "blockedDomains": [],
  "rateLimit":      { "calls": 500, "window": "1h" }
}

Response is the saved SpendPolicy object (same shape as request).

Agents

POST /v1/agents/invoke Invoke a sub-agent with a budget cap

Invoke a downstream sub-agent endpoint and authorize a USDC budget for that run. All payments made by the sub-agent are linked to the orchestrator's transaction on-chain via parentTxHash.

Request body

agentEndpoint

string

required

Full HTTPS URL of the sub-agent's invocation endpoint.

task

object

optional

Task payload forwarded to the sub-agent.

budget

{ usdc: number }

required

Maximum USDC the sub-agent is authorized to spend. Acts as a hard cap enforced at the gateway.

Response 200 OK

json

{
  "result": { ... },
  "paymentChain": [
    "5xGh9KmBv...",
    "7KLMnPqR2s..."
  ],
  "totalSpent": { "usdc": 0.018 }
}

ZK Privacy

POST /v1/shielded/deposit Deposit funds into the shielded pool

Move USDC from your transparent agent wallet into the shielded pool. The deposit transaction is public; the link between your wallet and future shielded payments is not.

Request body

usdc

number

required

Amount to deposit into the shielded pool.

Response 200 OK

json

{
  "depositTxHash": "public_solana_tx_hash",
  "note": "encrypted_private_note_store_securely",
  "shieldedBalance": { "usdc": 50 }
}

⚠️

Store the note value securely. It is not stored on-chain and cannot be recovered by Fixer Protocol if lost.

POST /v1/shielded/withdraw Withdraw from shielded pool

Withdraw USDC from the shielded pool back to a transparent wallet. Requires your private note to generate the Groth16 proof.

Request body

note

string

required

The encrypted private note from the original deposit.

recipient

string

required

Solana address to receive the withdrawn USDC.

usdc

number

required

Amount to withdraw. Must not exceed the commitment value.

GET /v1/shielded/balance/{agentId} Get shielded pool balance (encrypted)

Returns the sum of unspent commitments in the shielded pool for this agent, encrypted using your agent's ElGamal public key. Decryption requires your private key.

POST /v1/disclosure Generate a selective disclosure proof

Generate a ZK viewing credential for a specific private transaction. The credential can be sent to an auditor or compliance officer, it opens only the details of that one transaction, and only to the holder of the specified disclosureKey.

Request body

txHash

string

required

The Solana tx hash of the private transaction to disclose.

note

string

required

The private note associated with this transaction (from the original payment response).

disclosureKey

string

required

Solana public key of the party allowed to decrypt the transaction details.

Response 200 OK

json

{
  "disclosureProof": "zk_viewing_credential_base58...",
  "txHash": "5xGh9KmBv...",
  "disclosureKey": "recipient_public_key_base58"
}

Error Responses

All errors follow a consistent JSON envelope. Check the HTTP status code and the error.code field to handle specific cases.

json

{
  "error": {
    "code": "policy_violation",
    "message": "Payment would exceed daily budget of 100 USDC. Current spend: 99.80 USDC."
  }
}

HTTP Status	error.code	Description
400	`validation_error`	Request body is malformed or missing required fields.
401	`authentication_error`	API key is missing, invalid, or revoked.
402	`insufficient_funds`	Agent wallet balance is too low to cover the payment.
403	`policy_violation`	Payment blocked by an active spend policy (budget, allowlist, or rate limit).
404	`not_found`	The requested resource (transaction, agent, etc.) does not exist.
429	`rate_limit_exceeded`	Too many requests. Check the `Retry-After` header.
500	`internal_error`	Gateway internal error. Safe to retry with exponential backoff.
503	`solana_degraded`	Solana network is experiencing degraded performance. Payments may be delayed.

Endpoint Summary

Method	Path	Description
POST	`/v1/pay`	Route a transparent payment
POST	`/v1/pay/private`	Route a ZK-private payment
GET	`/v1/wallet/{agentId}`	Get wallet address and balance
POST	`/v1/wallet/{agentId}/fund`	Fund wallet balance
GET	`/v1/transactions`	List transactions (paginated)
GET	`/v1/transactions/{txHash}`	Get single transaction
GET	`/v1/policies/{agentId}`	Get current spend policy
PUT	`/v1/policies/{agentId}`	Set or replace spend policy
POST	`/v1/agents/invoke`	Invoke sub-agent with budget cap
POST	`/v1/shielded/deposit`	Deposit into shielded pool
POST	`/v1/shielded/withdraw`	Withdraw from shielded pool
GET	`/v1/shielded/balance/{agentId}`	Get encrypted shielded balance
POST	`/v1/disclosure`	Generate selective disclosure proof